Shamela

A NodeJS library for accessing and downloading Maktabah Shamela v4 APIs. This library provides easy-to-use functions to interact with the Shamela API, download master and book databases, and retrieve book data programmatically.

Table of Contents

• Installation
• Environment Variables
• Usage
  • Getting Started
  • API Functions
    • getMasterMetadata
    • downloadMasterDatabase
    • getBookMetadata
    • downloadBook
    • getBook
• Examples
  • Downloading the Master Database
  • Downloading a Book
  • Retrieving Book Data
• Testing
• License

Installation

npm install shamela

or

yarn add shamela

or

pnpm install shamela

Environment Variables

Before using the library, you need to set up some environment variables for API keys and endpoints:

SHAMELA_API_KEY: Your API key for accessing the Shamela API. SHAMELA_API_MASTER_PATCH_ENDPOINT: The endpoint URL for the master database patches. SHAMELA_API_BOOKS_ENDPOINT: The base endpoint URL for book-related API calls. You can set these variables in a .env file at the root of your project:

SHAMELA_API_KEY=your_api_key_here
SHAMELA_API_MASTER_PATCH_ENDPOINT=https://shamela.ws/api/master_patch
SHAMELA_API_BOOKS_ENDPOINT=https://shamela.ws/api/books

Usage

Getting Started

First, import the library functions into your project:

import { getMasterMetadata, downloadMasterDatabase, getBookMetadata, downloadBook, getBook } from 'shamela';

API Functions

getMasterMetadata

Fetches metadata for the master database.

getMasterMetadata(version?: number): Promise<GetMasterMetadataResponsePayload>

• version (optional): The version number of the master database you want to fetch.

Example:

const masterMetadata = await getMasterMetadata();

downloadMasterDatabase

Downloads the master database and saves it to a specified path.

downloadMasterDatabase(options: DownloadMasterOptions): Promise<string>

• options: An object containing:
  • masterMetadata (optional): The metadata obtained from getMasterMetadata.
  • outputFile: An object specifying the output path.

Example:

await downloadMasterDatabase({
    outputFile: { path: './master.db' },
});

getBookMetadata

Fetches metadata for a specific book.

getBookMetadata(id: number, options?: GetBookMetadataOptions): Promise<GetBookMetadataResponsePayload>

• id: The ID of the book.
• options (optional): An object containing:
  • majorVersion: The major version of the book.
  • minorVersion: The minor version of the book.

Example:

await downloadMasterDatabase({
    outputFile: { path: './master.db' },
});

getBook

Retrieves the data of a book as a JavaScript object.

getBook(id: number): Promise<BookData>

• id: The ID of the book.

Example:

const bookData = await getBook(26592);

Examples

Downloading the Master Database

import { downloadMasterDatabase } from 'shamela';

(async () => {
    await downloadMasterDatabase({
        outputFile: { path: './master.db' },
    });
})();

Downloading a Book

import { downloadBook } from 'shamela';

(async () => {
    await downloadBook(26592, {
        outputFile: { path: './book.db' },
    });
})();

Retrieving Book Data

import { getBook } from 'shamela';

(async () => {
    const bookData = await getBook(26592);
    console.log(bookData);
})();

Testing

The library includes tests to help you understand how the APIs are used. To run the tests, ensure you have the necessary environment variables set, then execute:

npm run test

For end-to-end tests:

npm run e2e

License

This project is licensed under the MIT License - see the LICENSE file for details.