islamic-content-sdk 1.0.1 → 1.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/islamic-content-sdk.svg)](https://www.npmjs.com/package/islamic-content-sdk)
 [![npm downloads](https://img.shields.io/npm/dm/islamic-content-sdk.svg)](https://www.npmjs.com/package/islamic-content-sdk)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/islamic-content-sdk)](https://bundlephobia.com/package/islamic-content-sdk)
+[![bundle size](https://badgen.net/bundlephobia/minzip/islamic-content-sdk)](https://bundlephobia.com/package/islamic-content-sdk)
 
 An integrated and easy-to-use software library for developers to fetch authentic Islamic content (The Holy Qur'an and Hadith) in multiple languages directly from official sources.
 
@@ -13,12 +13,13 @@ This project is developed for [The Association for Multi-lingual Islamic Content
 ## Services Overview
 
 This SDK aggregates content from multiple major multi-lingual Islamic platforms:
-* **QuranEnc (`quranenc`)**: Quran Translations, suras, verses, and audios.
-* **HadeethEnc (`hadeethenc`)**: Hadith collections, category trees, and grades.
-* **IslamHouse (`islamhouse`)**: Multi-lingual books, articles, audios, fatwas, and author details.
-* **Risalat Al-Haramain (`risalatAlHaramain`)**: Platform content, Fatwas, Quran recitations, and Hadiths.
-* **Bayan Al Islam (`bayanAlIslam`)**: Educational booklets and resources tailored for Muslims and Non-Muslims.
-* **Al Montaka (`alMontaka`)**: Structured lookups, categories, content filters, and community comments.
+
+- **QuranEnc (`quranenc`)**: Quran Translations, suras, verses, and audios.
+- **HadeethEnc (`hadeethenc`)**: Hadith collections, category trees, and grades.
+- **IslamHouse (`islamhouse`)**: Multi-lingual books, articles, audios, fatwas, and author details.
+- **Risalat Al-Haramain (`risalatAlHaramain`)**: Platform content, Fatwas, Quran recitations, and Hadiths.
+- **Bayan Al Islam (`bayanAlIslam`)**: Educational booklets and resources tailored for Muslims and Non-Muslims.
+- **Al Montaka (`alMontaka`)**: Structured lookups, categories, content filters, and community comments.
 
 ---
 
@@ -40,116 +41,424 @@ import { IslamicContentSdk } from "islamic-content-sdk";
 const sdk = new IslamicContentSdk();
 ```
 
+---
+
+## Detailed Service Methods Reference
+
+Below is a complete guide on how to interact with every single method and option available in the SDK.
+
 ### Quran Source (QuranEnc API)
 
+**API Documentation Link:** [QuranEnc API](https://quranenc.com/en/home/api/)
+
 ```typescript
-// 1. Get available translations
+// 1. Get available translations list on the platform
 const translations = await sdk.quranenc.translationList({
-  language: "es",
-  localization: "ar",
+  language: "es",      // Optional: Filter list by language code
+  localization: "ar"   // Optional: Localize names in the response
 });
 
 // 2. Translate an entire sura (Al-Fatiha in Spanish)
 const sura = await sdk.quranenc.translationSura("spanish_montada_eu", 1);
 
-// 3. Get the audio MP3 file details for a specific verse
+// 3. Translate a specific verse (Ayah 1 of Sura 1)
+const aya = await sdk.quranenc.translationAya("spanish_montada_eu", 1, 1);
+
+// 4. Get the audio MP3 file details for a specific verse
 const audio = await sdk.quranenc.ayaAudio("chinese_suliman", 1, 1);
+// Returns: { status: 200, file_url: "...", content_type: "audio/mpeg" }
+
+// 5. Submit translation feedback/note (POST request)
+const noteResponse = await sdk.quranenc.addNote({
+  sura: 1,
+  aya: 1,
+  name: "QA Tester",
+  email: "qa@example.com",
+  note: "Test note from SDK automated test suite",
+  translation_key: "spanish_montada_eu",
+  source: "sdk_test",
+  version: "1.0.0",
+  suggested_translation: "Suggested text" // Optional
+});
 ```
 
+---
+
 ### Hadith Source (HadeethEnc API)
 
+**API Documentation Link:** [HadeethEnc API](https://documenter.getpostman.com/view/5211979/TVev3j7q#intro)
+
 ```typescript
 // 1. Get available languages in the encyclopedia
 const languages = await sdk.hadeethenc.languages();
 
-// 2. Get main categories of Hadith in English
-const categories = await sdk.hadeethenc.rootCategories("en");
+// 2. Get all categories of Hadith translated in a specific language
+const categories = await sdk.hadeethenc.categories("en");
+
+// 3. Get main (root) categories of Hadith in English
+const rootCategories = await sdk.hadeethenc.rootCategories("en");
+
+// 4. List Hadiths under a category with pagination
+const hadiths = await sdk.hadeethenc.hadithsList({
+  language: "en",
+  categoryId: 1,  // Optional: Category ID
+  page: 1,        // Optional: Page number
+  perPage: 20     // Optional: Number of items per page
+});
 
-// 3. Get details of a specific Hadith by ID
-const hadith = await sdk.hadeethenc.hadithDetails({ id: 2962, language: "ar" });
+// 5. Get full explanation, translations, and grade of a specific Hadith by ID
+const hadith = await sdk.hadeethenc.hadithDetails({
+  id: 2962,
+  language: "ar"
+});
 ```
 
+---
+
 ### IslamHouse Source (IslamHouse v3 API)
 
+**API Documentation Link:** [IslamHouse API Docs](https://documenter.getpostman.com/view/7929737/TzkyMfPc)
+
 ```typescript
-// 1. Core material categories (videos, books, etc.)
-const content = await sdk.islamhouse.categoriesAndTypes.allTypes("ar", "ar");
+// ==========================================
+// 1. Categories & Types (categoriesAndTypes)
+// ==========================================
 
-// 2. Complete categories tree for materials
+// Core material types (videos, books, fatwas, etc.)
+const types = await sdk.islamhouse.categoriesAndTypes.allTypes("ar", "ar"); // siteLang, contentLang
+
+// Get all categories in the database
+const allCategories = await sdk.islamhouse.categoriesAndTypes.allCategories("ar");
+
+// Complete category hierarchy tree
 const tree = await sdk.islamhouse.categoriesAndTypes.categoriesTree("ar");
 
-// 3. List of sources and authors
-const authors = await sdk.islamhouse.authors.list({ page: 1, perPage: 10 });
+// Subcategories of a category with content lang localization
+const childCats = await sdk.islamhouse.categoriesAndTypes.childCategories(1, "ar", "ar"); // categoryId, siteLang, contentLang
+
+// Basic details of a category by ID
+const singleCategory = await sdk.islamhouse.categoriesAndTypes.singleCategoryBasic(1, "ar");
+
+// Subcategories with nested children
+const subCategories = await sdk.islamhouse.categoriesAndTypes.subCategories(1, "ar");
+
+// Available material types under a specific category ID
+const categoryTypes = await sdk.islamhouse.categoriesAndTypes.categoryTypes(1, "ar", "ar");
+
+// Available languages for materials within a category ID
+const categoryLangs = await sdk.islamhouse.categoriesAndTypes.categoryLanguages(1, "ar", "ar"); // id, slang, language
+
+// ==========================================
+// 2. Items Listings (items)
+// ==========================================
+
+// List materials by type (e.g. "books", "videos", "audios") and language
+const items = await sdk.islamhouse.items.listItems("books", "ar", "ar", 1, 25); // type, siteLang, slang, page, limit
+
+// List materials published by a specific author ID
+const authorItems = await sdk.islamhouse.items.authorItems(1, "ar", "ar", "ar", 1, 20); // authorId, slang, siteLang, contentLang, page, limit
+
+// List materials categorized under a category ID
+const catItems = await sdk.islamhouse.items.categoryItems(1, "ar", "ar", "ar", 1, 20); // categoryId, slang, siteLang, contentLang, page, limit
 
-// 4. View all categories
-const categories = await sdk.islamhouse.categoriesAndTypes.allCategories("ar");
+// List latest items by period (e.g., "week", "month")
+const latestItems = await sdk.islamhouse.items.latestItems("week", "ar", "ar", "ar", 1, 25); // period, slang, siteLang, contentLang, page, limit
 
-// 5. User interface localization terms for different languages
+// Highlighted featured items on the homepage
+const highlights = await sdk.islamhouse.items.highlightedItems("ar", "ar"); // siteLang, contentLang
+
+// Get the total count of items available for a specific type
+const itemsCount = await sdk.islamhouse.items.itemsCount("books", "ar", "ar"); // type, siteLang, contentLang
+
+// ==========================================
+// 3. Single Item Details (item)
+// ==========================================
+
+// Details, metadata, and description of a single item
+const itemDetails = await sdk.islamhouse.item.details(228065, "ar");
+
+// List downloadable media/PDF attachments for an item
+const attachments = await sdk.islamhouse.item.attachments(228065);
+
+// Category tree path leading to this item
+const itemTree = await sdk.islamhouse.item.tree(228065, "ar");
+
+// Translation card details of the item
+const itemCardTrans = await sdk.islamhouse.item.cardTranslations(228065, "ar");
+
+// Other translation languages available for this item
+const translations = await sdk.islamhouse.item.translations(228065, "ar");
+
+// ==========================================
+// 4. Authors and Publishers (authors)
+// ==========================================
+
+// List authors/sources with filter and sort parameters
+const authors = await sdk.islamhouse.authors.list({
+  kind: "author",     // Optional: "showall" | "author" | "source"
+  locale: "ar",       // Optional: "showall" | language code
+  sort: "countdesc",  // Optional
+  page: 1,            // Optional
+  perPage: 10         // Optional
+});
+
+// Specific author details by ID
+const authorDetails = await sdk.islamhouse.authors.details(1, "ar");
+
+// Translation card details of an author
+const authorCard = await sdk.islamhouse.authors.cardTranslations(1, "ar");
+
+// Material types available for an author
+const authorTypes = await sdk.islamhouse.authors.availableTypes(1, "ar", "ar");
+
+// Languages available for an author
+const authorLangs = await sdk.islamhouse.authors.availableLocales(1, "ar", "ar");
+
+// ==========================================
+// 5. Languages & Terms (languages)
+// ==========================================
+
+// Details of all supported languages on the platform
+const langKeys = await sdk.islamhouse.languages.keys();
+
+// Interface translation terms for localization
 const terms = await sdk.islamhouse.languages.terms("ar");
 
-// 6. Details of a specific Quran recitation by ID
+// Available languages relative to another
+const availLangs = await sdk.islamhouse.languages.availableLanguages("ar", "ar");
+
+// ==========================================
+// 6. Holy Quran Recitations (quran)
+// ==========================================
+
+// Quran recitation categories (reciters, sections)
+const quranCategories = await sdk.islamhouse.quran.categories("ar");
+
+// Basic details of a Quran category
+const quranCategory = await sdk.islamhouse.quran.singleCategory(1, "ar");
+
+// Details about a specific reciter
+const reciterDetails = await sdk.islamhouse.quran.authorDetails(1, "ar");
+
+// Recitations list of a specific reciter
+const recitations = await sdk.islamhouse.quran.authorRecitations(1, "ar");
+
+// Detailed info of a specific Quran Surah
+const suraDetails = await sdk.islamhouse.quran.suraDetails(1, "ar");
+
+// Audio recordings of a specific Surah by various reciters
+const suraRecitations = await sdk.islamhouse.quran.suraRecitations(1, "ar");
+
+// Details of a specific Quran recitation by ID
 const recitation = await sdk.islamhouse.quran.recitationDetails(228065, "ar");
 ```
 
+---
+
 ### Risalat Al-Haramain Source (Risalat Al-Haramain API)
 
+**API Documentation Link:** [Risalat Al-Haramain API](https://risala.prh.gov.sa/en/Api/content)
+
 ```typescript
-// 1. Get available languages
-const risalaLangs = await sdk.risalatAlHaramain.lookups.languages();
+// ==========================================
+// 1. Platform Contents (contents)
+// ==========================================
 
-// 2. Get full content of the platform in a specific language
+// Get full content of the platform in a specific language
 const fullContents = await sdk.risalatAlHaramain.contents.getFullContents({
-  lang: "en",
+  language: "en", // Optional: URL language path (default: "en")
+  lang: "en"     // Optional: Query parameter language (default: "en")
+});
+
+// Retrieve contents with optional parameters
+const contents = await sdk.risalatAlHaramain.contents.getContents({
+  language: "en",
+  lang: "en"
+});
+
+// Get detailed content of a single item
+const singleContent = await sdk.risalatAlHaramain.contents.singleContent(1, "en");
+
+// Quick search items by name
+const nameSearchResult = await sdk.risalatAlHaramain.contents.nameSearch("حصن", "ar");
+
+// Check available translation languages for an item
+const risalaAvailLangs = await sdk.risalatAlHaramain.contents.availableLanguages(1, "ar");
+
+// Get translation of a content item into a target language
+const contentTranslation = await sdk.risalatAlHaramain.contents.contentTranslation(1, "en", "ar"); // id, targetLanguage, language
+
+// ==========================================
+// 2. Islamic Content Modules (islamicContent)
+// ==========================================
+
+// Get Fatwas
+const fatwas = await sdk.risalatAlHaramain.islamicContent.fatwas({
+  language: "en",    // Optional
+  lang: "ar",        // Optional
+  isFeatured: 1      // Optional: 0 or 1
 });
 
-// 3. Get featured Holy Quran content
+// Get featured Hadiths
+const hadeeths = await sdk.risalatAlHaramain.islamicContent.hadeeths({
+  language: "en",
+  lang: "ar",
+  isFeatured: 1
+});
+
+// Get featured Quran recitations
 const quranContent = await sdk.risalatAlHaramain.islamicContent.quran({
+  language: "en",
   lang: "ar",
+  isFeatured: 1
 });
 
-// 4. Text search in content
-const searchResult = await sdk.risalatAlHaramain.search.contents("حصن");
+// ==========================================
+// 3. Platform Search (search)
+// ==========================================
+
+// Keyword text search across platform content
+const searchResult = await sdk.risalatAlHaramain.search.contents("حصن", "en");
+
+// ==========================================
+// 4. Lookups & Meta (lookups)
+// ==========================================
+
+// Get available languages
+const risalaLangs = await sdk.risalatAlHaramain.lookups.languages("en");
+
+// Get available content types
+const contentTypes = await sdk.risalatAlHaramain.lookups.contentTypes("en");
 ```
 
+---
+
 ### Bayan Al Islam Source (Bayan Al Islam API)
 
+**Postman Resources:** [Collection](https://byenah.com/download-request?name=Bayan%20Al%20Islam.postman_collection.json) | [Environment](https://byenah.com/download-request?name=Bayan%20al%20islam%20env.postman_environment.json)
+
 ```typescript
 // 1. Get list of available languages
-const bayanLangs = await sdk.bayanAlIslam.languagesList();
+const bayanLangs = await sdk.bayanAlIslam.languagesList("ar");
 
-// 2. Get content list for Muslims
+// 2. Get content list tailored for Muslims
 const muslimList = await sdk.bayanAlIslam.muslimList("en");
 
-// 3. Get content list for non-Muslims
+// 3. Get content list tailored for Non-Muslims
 const nonMuslimList = await sdk.bayanAlIslam.nonMuslimList("en");
 
 // 4. Get details of a specific content item by ID
-const contentDetails = await sdk.bayanAlIslam.singleContent(22184);
+const contentDetails = await sdk.bayanAlIslam.singleContent(22184, "en");
 
-// 5. Get recent additions
+// 5. Get languages list paginated and filtered by name
+const paginatedLangs = await sdk.bayanAlIslam.paginatedLanguages({
+  name: "English", // Optional
+  page: 1,         // Optional
+  language: "en"   // Optional
+});
+
+// 6. Get recent contents (Muslim/Non-Muslim updates)
 const recent = await sdk.bayanAlIslam.recentContents({
   lang: "ar",
   init: true,
+  ids: [22184], // Optional: content IDs list
+  language: "en" // Optional
 });
+
+// 7. Get website lookup variables
+const lookups = await sdk.bayanAlIslam.lookups("en");
+
+// 8. Search materials by title/name
+const searchResult = await sdk.bayanAlIslam.nameSearch("حصن", "ar");
+
+// 9. Check available translation languages for a content ID
+const availLangs = await sdk.bayanAlIslam.availableLanguages(22184, "ar");
+
+// 10. Get specific translation of a content item
+const translation = await sdk.bayanAlIslam.contentTranslation(22184, "en", "ar"); // id, targetLanguage, language
+
+// 11. Get translations for media or PDF attachments of a content item
+const attachmentsTrans = await sdk.bayanAlIslam.attachmentsTranslation(22184, "en", "ar"); // id, targetLanguage, language
 ```
 
+---
+
 ### Al Montaka Source (Al Montaka API)
 
-```typescript
-// 1. Get available languages
-const languages = await sdk.alMontaka.lookups.languages();
+**API Documentation Link:** [Al Montaka API](https://documenter.getpostman.com/view/5211979/2s8YzMZ6Fu)
 
-// 2. Get target age groups
-const ageGroups = await sdk.alMontaka.lookups.ageGroups();
+```typescript
+// ==========================================
+// 1. Content and Comments (contents)
+// ==========================================
 
-// 3. Get comments for a specific content ID
+// Get all comments for a specific content ID
 const comments = await sdk.alMontaka.contents.comments(1);
 
-// 4. Add a new comment to a specific content
+// Add a new comment to a specific content item
 const newComment = await sdk.alMontaka.contents.addComment(1, "Test comment");
 
-// 5. Get filtered content by category IDs
+// Get filtered content by category IDs
 const filteredContent = await sdk.alMontaka.contents.content([1, 2]);
+
+// ==========================================
+// 2. Site Lookups and Filters (lookups)
+// ==========================================
+
+// Get target age groups
+const ageGroups = await sdk.alMontaka.lookups.ageGroups();
+
+// Get categories matching language and name filter
+const categories = await sdk.alMontaka.lookups.categories({
+  languageId: 1,
+  nameCont: "General"
+});
+
+// Get publishing entities matching language and name filter
+const entities = await sdk.alMontaka.lookups.entities({
+  languageId: 1,
+  nameCont: "Dar"
+});
+
+// Get expertise/scientific levels matching filter
+const expertLevels = await sdk.alMontaka.lookups.expertLevels({
+  languageId: 1,
+  nameCont: "Level"
+});
+
+// Get ideologies matching filter
+const ideologies = await sdk.alMontaka.lookups.ideologies({
+  languageId: 1,
+  nameCont: "Sunnah",
+  parentId: 0
+});
+
+// Get available languages
+const languages = await sdk.alMontaka.lookups.languages();
+
+// Get/search scholars, narrators, or personalities
+const persons = await sdk.alMontaka.lookups.persons({
+  nameCont: "Muhammad", // Optional
+  page: 1              // Optional
+});
+
+// Get website sections matching filter
+const sections = await sdk.alMontaka.lookups.sections({
+  languageId: 1,
+  nameCont: "Section"
+});
+
+// Get tags matching filter
+const tags = await sdk.alMontaka.lookups.tags({
+  languageId: 1,
+  nameCont: "Tag"
+});
+
+// Get targeted groups of audience
+const targetedGroups = await sdk.alMontaka.lookups.targetedGroups();
+
+// Get integrated YouTube channels list
+const youtubeChannels = await sdk.alMontaka.lookups.youtubeChannels();
 ```
 
 ---
@@ -157,7 +466,8 @@ const filteredContent = await sdk.alMontaka.contents.content([1, 2]);
 ## Donation & Support
 
 You can support the projects and efforts of The Association for Multi-lingual Islamic Content through the following official channels:
-* [Support Projects (Wakfy)](https://islamiccontent.org/Wakfy)
-* [Bank Accounts](https://islamiccontent.org/Accounts)
-* [Association Store](https://store.islamiccontent.sa/)
 
+- [Support Projects (Wakfy)](https://islamiccontent.org/Wakfy)
+- [Bank Accounts](https://islamiccontent.org/Accounts)
+- [Association Store](https://store.islamiccontent.sa/)
+- [Annual Operational Support (الدعم التشغيلي السنوي للجمعية)](https://store.islamiccontent.sa/%D8%A7%D9%84%D9%85%D8%B5%D8%B1%D9%8وفات-%D8%A7%D9%84%D8%AA%D8%B4%D8%BA%D9%8A%D9%84%D9%8A%D8%A9-%D8%A7%D9%84%D8%B3%D9%86%D9%88%D9%8A%D8%A9-%D9%84%D9%84%D8%AC%D9%85%D8%B9%D9%8A-%D8%A9/p1950956689)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "islamic-content-sdk",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "",
   "main": "dist/index.js",
   "module": "dist/index.mjs",