turath-sdk

KO | EN

gitlite — search

#javascript #python #hacktoberfest #ai #go #machine-learning #rust #linux #java #windows #awesome #vue #pytorch #openai

(★ 15)

JavaScript SDK for accessing turath.io books

turath-sdk Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![wakatime](https://wakatime.com/badge/user/a0b906ce-b8e7-4463-8bce-383238df6d4b/project/c57d4b46-a567-4de0-9c97-a4589b33f8ee.svg)](https://wakatime.com/badge/user/a0b906ce-b8e7-4463-8bce-383238df6d4b/project/c57d4b46-a567-4de0-9c97-a4589b33f8ee)
[![E2E](https://github.com/ragaeeb/turath-sdk/actions/workflows/e2e.yml/badge.svg)](https://github.com/ragaeeb/turath-sdk/actions/workflows/e2e.yml)
[![Node.js CI](https://github.com/ragaeeb/turath-sdk/actions/workflows/build.yml/badge.svg)](https://github.com/ragaeeb/turath-sdk/actions/workflows/build.yml)
![GitHub License](https://img.shields.io/github/license/ragaeeb/turath-sdk)
![GitHub Release](https://img.shields.io/github/v/release/ragaeeb/turath-sdk)
[![codecov](https://codecov.io/gh/ragaeeb/turath-sdk/graph/badge.svg?token=82MVUIM7MJ)](https://codecov.io/gh/ragaeeb/turath-sdk)
[![Size](https://deno.bundlejs.com/badge?q=turath-sdk@latest)](https://bundlejs.com/?q=turath-sdk%40latest)
![typescript](https://badgen.net/badge/icon/typescript?icon=typescript&label&color=blue)
![npm](https://img.shields.io/npm/v/turath-sdk)
![npm](https://img.shields.io/npm/dm/turath-sdk)
![GitHub issues](https://img.shields.io/github/issues/ragaeeb/turath-sdk)
![GitHub stars](https://img.shields.io/github/stars/ragaeeb/turath-sdk?style=social)

# 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:

```bash
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](https://bun.sh/) for dependency management and testing during development.

```bash
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

```javascript
import { getBookInfo } from 'turath-sdk';
```

### 1. `getAuthor`

Fetches information about an author by their ID.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

turath-sdk

turath-sdk Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

turath-sdk

turath-sdk Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README