Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ragaeeb/shamela/llms.txt
Use this file to discover all available pages before exploring further.
Overview
This function fetches book release information including major and minor release URLs and version numbers from the Shamela web service.
Function Signature
getBookMetadata(id: number, options?: GetBookMetadataOptions): Promise<GetBookMetadataResponsePayload>
Parameters
The unique identifier of the book to fetch metadata for
Optional parameters for specifying major and minor versions
Major version number to check for updates
Minor version number to check for updates
Returns
GetBookMetadataResponsePayload
Book metadata including release URLs and versions
Major release version number
Download URL for the major release of the book
Minor release version number (if available)
Download URL for the minor release/patch (if available)
Examples
import { getBookMetadata } from 'shamela';
const metadata = await getBookMetadata(26592);
console.log(`Major Release: v${metadata.majorRelease}`);
console.log(`Download URL: ${metadata.majorReleaseUrl}`);
if (metadata.minorReleaseUrl) {
console.log(`Patch available: v${metadata.minorRelease}`);
console.log(`Patch URL: ${metadata.minorReleaseUrl}`);
}
Check for Updates
const bookId = 123;
const currentMajor = 1;
const currentMinor = 2;
const metadata = await getBookMetadata(bookId, {
majorVersion: currentMajor,
minorVersion: currentMinor
});
if (metadata.majorRelease > currentMajor) {
console.log('Major update available!');
} else if (metadata.minorRelease && metadata.minorRelease > currentMinor) {
console.log('Patch update available!');
} else {
console.log('Book is up to date');
}
Fetch Before Downloading
import { getBookMetadata, downloadBook } from 'shamela';
const bookId = 26592;
// Fetch metadata first to check versions
const metadata = await getBookMetadata(bookId);
console.log(`Downloading book v${metadata.majorRelease}`);
// Use metadata in download to avoid re-fetching
await downloadBook(bookId, {
bookMetadata: metadata,
outputFile: { path: `./book_${bookId}.json` }
});
Response Details
Major vs Minor Releases
- Major Release: The main book database file
- Minor Release: Optional patch file with corrections or additions
- If a minor release exists, it should be applied on top of the major release
downloadBook function automatically handles applying patches when both releases are available.
Error Handling
This function throws an error when:
- Required environment variables (
booksEndpoint) are not set
- API request fails
- Network connection issues occur
- Invalid book ID is provided
try {
const metadata = await getBookMetadata(26592);
} catch (error) {
if (error.message.includes('404')) {
console.error('Book not found');
} else {
console.error('Failed to fetch metadata:', error.message);
}
}
Configuration Requirements
Ensure the booksEndpoint is configured before calling this function:
import { configure } from 'shamela';
configure({
apiKey: process.env.SHAMELA_API_KEY,
booksEndpoint: process.env.SHAMELA_BOOKS_ENDPOINT
});
- downloadBook - Download a book using this metadata
- getBook - Retrieve book data as a JavaScript object
- getCoverUrl - Generate the cover image URL for a book