@zensearch/docs-sdk

Official JavaScript/TypeScript SDK for ZenSearch Documentation Search.

Installation

npm install @zensearch/docs-sdk
# or
yarn add @zensearch/docs-sdk
# or
pnpm add @zensearch/docs-sdk

Quick Start

import { ZenSearchDocs } from '@zensearch/docs-sdk';

// Initialize with your API key
const client = new ZenSearchDocs({
  apiKey: 'zsk_pk_xxx...', // Publishable key for client-side
  defaultCollection: 'your-collection-id', // Optional
});

// Search documentation
const results = await client.search('how to install');
console.log(results.results);

// Get autocomplete suggestions
const suggestions = await client.autocomplete('auth');
console.log(suggestions.suggestions);

Configuration

const client = new ZenSearchDocs({
  // Required: Your API key (publishable for client-side, secret for server-side)
  apiKey: 'zsk_pk_xxx...',

  // Optional: Custom API base URL
  baseUrl: 'https://api.zensearch.dev',

  // Optional: Default collection to search
  defaultCollection: 'collection-uuid',

  // Optional: Request timeout in milliseconds (default: 30000)
  timeout: 30000,

  // Optional: Custom fetch implementation (for Node.js)
  fetch: customFetch,
});

API Reference

search(query, options?)

Search documentation with various filtering options.

const results = await client.search('authentication', {
  limit: 10,           // Max results (default: 10, max: 100)
  offset: 0,           // Pagination offset
  minScore: 0.5,       // Min relevance score (0-1, default: 0.5)
  highlight: true,     // Enable term highlighting
  section: 'guides',   // Filter by section
  version: '2.0',      // Filter by version
  tags: ['security'],  // Filter by tags
});

Response

{
  results: [
    {
      url: 'https://docs.example.com/auth',
      title: 'Authentication Guide',
      snippet: 'Learn how to implement <mark>authentication</mark>...',
      hierarchy: ['Guides', 'Security', 'Authentication'],
      level: 2,
      score: 0.95,
      suType: 'section',
      highlights: {
        title: '<mark>Authentication</mark> Guide',
        content: 'Learn how to implement <mark>authentication</mark>...',
      },
    },
  ],
  queryId: 'query-uuid',
  tookMs: 42,
  totalHits: 15,
  hasMore: true,
}

autocomplete(query, options?)

Get search suggestions as the user types.

const suggestions = await client.autocomplete('auth', {
  limit: 5,  // Max suggestions (default: 5, max: 20)
});

Response

{
  query: 'auth',
  suggestions: [
    {
      text: 'Authentication',
      type: 'title',
      score: 0.9,
      hierarchy: 'Guides > Security',
      url: 'https://docs.example.com/auth',
    },
    {
      text: 'Authorization',
      type: 'heading',
      score: 0.85,
    },
  ],
}

getDocument(documentId)

Retrieve a specific document by ID.

const doc = await client.getDocument('document-uuid');

trackEvent(event)

Track analytics events for search improvements.

// Track a click on a search result
await client.trackEvent({
  type: 'click',
  queryId: results.queryId,
  url: results.results[0].url,
  position: 1,
});

// Track user feedback
await client.trackEvent({
  type: 'feedback',
  queryId: results.queryId,
  rating: 5,
});

Error Handling

import { ZenSearchDocs, ZenSearchError } from '@zensearch/docs-sdk';

try {
  const results = await client.search('query');
} catch (error) {
  if (error instanceof ZenSearchError) {
    if (error.isAuthError()) {
      console.error('Authentication failed');
    } else if (error.isRateLimitError()) {
      console.error('Rate limit exceeded');
    } else {
      console.error(`Error: ${error.message} (${error.status})`);
    }
  }
}

Request Cancellation

const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  const results = await client.search('query', {
    signal: controller.signal,
  });
} catch (error) {
  if (error instanceof ZenSearchError && error.status === 408) {
    console.log('Request was cancelled');
  }
}

TypeScript Support

Full TypeScript support with exported types:

import type {
  SearchOptions,
  SearchResponse,
  SearchResult,
  AutocompleteOptions,
  AutocompleteResponse,
  Document,
} from '@zensearch/docs-sdk';

Framework Integration

React

import { useState, useEffect } from 'react';
import { ZenSearchDocs } from '@zensearch/docs-sdk';

const client = new ZenSearchDocs({ apiKey: 'zsk_pk_xxx...' });

function SearchBox() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  useEffect(() => {
    if (query.length < 2) return;

    const controller = new AbortController();

    client.search(query, { signal: controller.signal })
      .then(res => setResults(res.results))
      .catch(() => {});

    return () => controller.abort();
  }, [query]);

  return (
    <div>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <ul>
        {results.map(r => (
          <li key={r.url}>{r.title}</li>
        ))}
      </ul>
    </div>
  );
}

Node.js / Server-Side

import { ZenSearchDocs } from '@zensearch/docs-sdk';

// Use secret key for server-side
const client = new ZenSearchDocs({
  apiKey: process.env.ZENSEARCH_SECRET_KEY,
});

License

MIT