turath-sdk

JavaScript SDK for accessing the books and resources provided by turath.io. This SDK allows you to interact with the turath.io API to retrieve book information, author details, specific pages, and perform searches across the database.

Installation

Install turath-sdk using your preferred JavaScript package manager:

bun add turath-sdk
# or
npm install turath-sdk
# or
yarn add turath-sdk

Requirements

Node.js >= 22.0.0

Development

This repository uses Bun for dependency management and testing during development.

bun install
bun run build
bun test           # unit tests with coverage
bun test testing   # end-to-end tests
bun run lint       # Biome static analysis

Exports

The SDK exports strongly-typed helpers and data structures for working with turath.io:

| Export | Type | Description | | --- | --- | --- | | getAuthor | (id: number) => Promise<AuthorApiResponse> | Fetch author biography metadata. | | getBookFile | (id: number) => Promise<BookFileApiResponse> | Retrieve the full JSON dump for a book. | | getBookInfo | (id: number) => Promise<BookApiResponse> | Fetch high-level book metadata and indexes. | | getPage | (bookId: number, pageNumber: number) => Promise<PageResult> | Load a parsed page including metadata. | | search | (query: string, options?: SearchOptions) => Promise<SearchResults> | Run catalog searches with filters. | | SortField | enum | Sorting options for the search helper. | | SearchOptions | type | Optional filters accepted by search. | | SearchResult | type | Parsed representation of a single search hit. | | SearchResults | type | Envelope returned by the search helper. | | PageMetadata | type | Metadata describing page attribution and headings. | | PageResult | type | Page lookup result combining text and metadata. |

Usage

The sections below demonstrate how to use each helper and highlight the available options.

Importing the SDK

import { getBookInfo } from 'turath-sdk';

1. getAuthor

Fetches information about an author by their ID.

import { getAuthor } from 'turath-sdk';

(async () => {
    try {
        const author = await getAuthor(44);
        console.log(author);
    } catch (error) {
        console.error(error.message);
    }
})();

Parameters:

id (number): The unique identifier of the author.

Returns: A promise that resolves to the author's information.

Throws: Will throw an error if the author is not found.

2. getBookFile

Fetches the JSON file of a book by its ID.

import { getBookFile } from 'turath-sdk';

(async () => {
    try {
        const bookFile = await getBookFile(147927);
        console.log(bookFile);
    } catch (error) {
        console.error(error.message);
    }
})();

Parameters:

id (number): The unique identifier of the book.

Returns: A promise that resolves to the book file information.

Throws: Will throw an error if the book file is not found.

3. getBookInfo

Fetches the information about a book, including its metadata and indexes.

import { getBookInfo } from 'turath-sdk';

(async () => {
    const bookInfo = await getBookInfo(147927);
    console.log(bookInfo);
})();

Parameters:

id (number): The unique identifier of the book.

Returns: A promise that resolves to the book information including indexes.

4. getPage

Fetches a specific page from a book by its book ID and page number.

import { getPage } from 'turath-sdk';

(async () => {
    try {
        const page = await getPage(147927, 5);
        console.log(page);
    } catch (error) {
        console.error(error.message);
    }
})();

Parameters:

bookId (number): The unique identifier of the book.

pageNumber (number): The page number to retrieve.

Returns: A promise that resolves to the page metadata and text.

Throws: Will throw an error if the page is not found.

5. search

Searches for books or content using a query string.

import { search } from 'turath-sdk';

(async () => {
    const results = await search('الإسلام', { category: 6 });
    console.log(results);
})();

Parameters:

query (string): The search query string.

options (SearchOptions, optional): Additional search options such as category or sorting field. Available options are:

• author (number): Filter results to a specific author ID.
• book (number): Restrict matches to a single book ID.
• category (number): Filter by category identifier.
• page (number): Retrieve a specific page of results.
• precision (number): Pass-through precision flag used by the API.
• sortField (SortField): Sort the results (currently SortField.PageId).

Returns: A promise that resolves to the search results, including count and data.

Contributing

If you'd like to contribute to the SDK, feel free to fork the repository and submit a pull request. Contributions are welcome!

License

This SDK is licensed under the MIT License.