sefaria-sdk

Zero-dependency TypeScript SDK for the Sefaria API. Provides typed access to Jewish texts, translations, search, topics, and more.

Install

npm install sefaria-sdk
# or
bun add sefaria-sdk

Quick start

Using createClient

import { createClient } from 'sefaria-sdk';

const sefaria = createClient();

const result = await sefaria.getText('Genesis 1:1');
if (result.ok) {
  console.log(result.data.versions[0].text);
}

Standalone functions

import { getText, searchText } from 'sefaria-sdk';

const result = await getText('Berakhot 2a');
if (result.ok) {
  console.log(result.data.ref);
}

Error handling

Every function returns a Result<T, R> — either { ok: true, data: T } or { ok: false, reason: R }.

import { getText, SefariaReason } from 'sefaria-sdk';

const result = await getText('Genesis 1:1', { language: 'english' });

if (!result.ok) {
  switch (result.reason) {
    case SefariaReason.NoTranslation:
      console.log('No translation available');
      break;
    case SefariaReason.NoVersion:
      console.log('No version found');
      break;
  }
}

Network and HTTP errors throw typed exceptions:

import { getText, NetworkError, ApiError, NotFoundError } from 'sefaria-sdk';

try {
  await getText('Genesis 1:1');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Not found:', err.endpoint);
  } else if (err instanceof NetworkError) {
    console.log('Network issue:', err.message);
  } else if (err instanceof ApiError) {
    console.log(`API error ${err.status}:`, err.message);
  }
}

API reference

Texts

| Function | Description | |---|---| | getText(ref, options?) | Fetch a text passage by reference | | getVersions(title, options?) | List available versions of a text | | getLanguages(options?) | List all available languages | | getTranslations(language, options?) | List translations for a language | | getRandomText(options?) | Get a random text reference |

Links

| Function | Description | |---|---| | getLinks(ref, options?) | Get links/connections for a reference | | getRelated(ref, options?) | Get related content for a reference | | getRefTopicLinks(ref, options?) | Get topic links for a reference |

Search

| Function | Description | |---|---| | searchText(query, options?) | Full-text search across the library | | searchInBook(query, book, options?) | Search within a specific book | | semanticSearch(query, options?) | Semantic/vector search |

Topics

| Function | Description | |---|---| | getTopic(slug, options?) | Get a topic by slug | | getAllTopics(options?) | List all topics |

Calendar

| Function | Description | |---|---| | getCalendar(options?) | Get today's calendar readings |

Names

| Function | Description | |---|---| | resolveName(name, options?) | Resolve/autocomplete a text name |

Manuscripts

| Function | Description | |---|---| | getManuscripts(ref, options?) | Get manuscript images for a reference |

Dictionary

| Function | Description | |---|---| | lookupWord(word, options?) | Look up a word in dictionaries |

Categories

| Function | Description | |---|---| | getIndex(title, options?) | Get index metadata for a text | | getTableOfContents(options?) | Get the full table of contents | | getShape(name, options?) | Get the shape/structure of a text | | getCategory(name, options?) | Get a category and its contents |

Utility

| Function | Description | |---|---| | findRefs(text, options?) | Find text references in a string | | getTerm(name, options?) | Look up a term/schema node |

Configuration

Options can be passed to createClient() or in each function's options bag.

| Option | Type | Default | Description | |---|---|---|---| | baseUrl | string | https://www.sefaria.org | API base URL | | timeout | number | 10000 | Request timeout in ms | | maxRetries | number | 2 | Retries for 429/5xx errors | | fetch | typeof fetch | globalThis.fetch | Custom fetch implementation | | signal | AbortSignal | — | Abort signal for cancellation |

Per-call config overrides client-level config:

const client = createClient({ timeout: 5000 });

// This call uses timeout: 30000, not 5000
await client.getText('Genesis 1:1', { config: { timeout: 30000 } });

License

MIT