index.js

/**
 * @contextwire/sdk — Official Node.js SDK for ContextWire
 * https://contextwire.dev
 *
 * Usage:
 *   import { ContextWire } from '@contextwire/sdk';
 *   const cw = new ContextWire('YOUR_API_KEY');
 *   const answer = await cw.ask('Who invented the telephone?');
 *   console.log(answer.answer); // "Alexander Graham Bell"
 */

const DEFAULT_BASE = 'https://contextwire.dev/api';

export class ContextWire {
  #key;
  #base;
  #timeout;

  /**
   * @param {string} apiKey - Your ContextWire API key
   * @param {object} [options]
   * @param {string} [options.baseUrl] - API base URL (default: https://contextwire.dev/api)
   * @param {number} [options.timeout] - Request timeout in ms (default: 30000)
   */
  constructor(apiKey, options = {}) {
    if (!apiKey) throw new Error('API key is required. Get one at https://contextwire.dev/#signup');
    this.#key = apiKey;
    this.#base = (options.baseUrl || DEFAULT_BASE).replace(/\/+$/, '');
    this.#timeout = options.timeout || 30000;
  }

  async #fetch(path, options = {}) {
    const url = `${this.#base}${path}`;
    const res = await fetch(url, {
      ...options,
      headers: {
        'Authorization': `Bearer ${this.#key}`,
        'Content-Type': 'application/json',
        ...options.headers,
      },
      signal: AbortSignal.timeout(this.#timeout),
    });
    if (!res.ok) {
      const body = await res.text();
      throw new Error(`ContextWire API error ${res.status}: ${body}`);
    }
    return res.json();
  }

  /**
   * Ask a factual question — full research loop (94.3% on SimpleQA).
   * @param {string} question
   * @returns {Promise<{answer: string, source: string, latency_ms: number, sources: Array, pageExcerpts: Array}>}
   */
  async ask(question) {
    return this.#fetch(`/ask?q=${encodeURIComponent(question)}`);
  }

  /**
   * Search the web using 100+ engines.
   * @param {string} query
   * @param {object} [options]
   * @param {string} [options.profile] - Search profile (web, news, academic, code, etc.)
   * @param {number} [options.maxResults] - Max results (1-100, default: 10)
   * @param {string} [options.freshness] - Time filter (day, week, month, year)
   * @param {number} [options.includeContent] - Number of results to fetch full content for
   * @returns {Promise<{results: Array, answer?: string, suggestions?: Array}>}
   */
  async search(query, options = {}) {
    const params = new URLSearchParams({ q: query, format: 'json' });
    if (options.profile) params.set('profile', options.profile);
    if (options.maxResults) params.set('max_results', String(options.maxResults));
    if (options.freshness) params.set('freshness', options.freshness);
    if (options.includeContent) params.set('include_content', String(options.includeContent));
    return this.#fetch(`/search?${params}`);
  }

  /**
   * Extract clean text or markdown from a URL.
   * @param {string} url - URL to extract content from
   * @param {'text'|'markdown'} [format='text']
   * @returns {Promise<{title: string, url: string, content: string, word_count: number}>}
   */
  async extract(url, format = 'text') {
    return this.#fetch(`/extract?url=${encodeURIComponent(url)}&format=${format}`);
  }

  /**
   * Search academic papers (arXiv, Semantic Scholar, CrossRef, PubMed, OpenAlex).
   * @param {string} query
   * @param {number} [maxPapers=5]
   * @returns {Promise<{papers: Array}>}
   */
  async research(query, maxPapers = 5) {
    return this.#fetch(`/research?q=${encodeURIComponent(query)}&max_papers=${maxPapers}`);
  }

  /**
   * Run multiple searches in parallel.
   * @param {Array<{q: string, profile?: string, max_results?: number}>} queries
   * @returns {Promise<{results: Array}>}
   */
  async batchSearch(queries) {
    return this.#fetch('/search/batch', {
      method: 'POST',
      body: JSON.stringify({ queries }),
    });
  }

  /**
   * Get autocomplete suggestions.
   * @param {string} query - Partial query
   * @returns {Promise<{suggestions: string[]}>}
   */
  async suggest(query) {
    return this.#fetch(`/suggest?q=${encodeURIComponent(query)}`);
  }

  /**
   * List available search engines.
   * @param {string} [category] - Filter by category
   * @returns {Promise<{engines: Array}>}
   */
  async engines(category) {
    const params = category ? `?category=${encodeURIComponent(category)}` : '';
    return this.#fetch(`/engines${params}`);
  }

  /**
   * List all search profiles.
   * @returns {Promise<{profiles: Array}>}
   */
  async profiles() {
    return this.#fetch('/profiles');
  }

  /**
   * Check API health.
   * @returns {Promise<{status: string, version: string}>}
   */
  async health() {
    return this.#fetch('/health');
  }
}

export default ContextWire;