deen-api-client 1.0.0 → 1.1.0

package/README.md

@@ -2,6 +2,42 @@
 
 A Node.js client for the Deen API, providing easy access to Islamic resources including Hadith, Quran verses, and Duas.
 
+## Getting an API Key
+
+To use the Deen API, you'll need a valid API key. Follow these steps to get yours:
+
+### Step 1: Visit the API Keys Page
+
+Go to **[https://deen.imaniro.com/api-keys](https://deen.imaniro.com/api-keys)** to access your API key dashboard.
+
+### Step 2: Sign In or Create an Account
+
+- If you already have an account, sign in with your credentials
+- New user? Click on "Create Account" and fill in the registration form
+
+### Step 3: Generate Your API Key
+
+1. Once logged in, navigate to the **API Keys** section
+2. Click the **"Generate New Key"** button
+3. Give your key a descriptive name (e.g., "Production App", "Development Server")
+4. Select the appropriate permissions/plan for your needs
+5. Click **"Generate New Key"** to generate your key
+
+### Step 4: Copy and Secure Your Key
+
+- Store it securely (use environment variables, never commit to version control)
+- Consider using a password manager or secure vault
+
+### 💡 Best Practices for API Key Security
+
+```javascript
+// DON'T: Hardcode your API key
+const client = new ImaniroDeenAPIClient('your_api_key_here');
+
+// DO: Use environment variables
+const client = new ImaniroDeenAPIClient(process.env.DEEN_API_KEY);
+```
+
 ## Installation
 
 ```bash
@@ -22,12 +58,15 @@ const client = new ImaniroDeenAPIClient('your_api_key_here');
 // Get hadiths from Sahih al-Bukhari
 async function getHadiths() {
   try {
-    const hadiths = await client.getHadiths('Sahih al-Bukhari', 5);
+    const hadiths = await client.getHadiths({
+      book: 'Sahih al-Bukhari',
+      maxLimit: 1,
+    });
 
     hadiths.forEach((hadith) => {
       console.log(`Book: ${hadith.book}`);
-      console.log(`Chapter: ${hadith.chapter}`);
-      console.log(`Text: ${hadith.text}`);
+      console.log(`Hadith Number: ${hadith.number}`);
+      console.log(`Arabic Text: ${hadith.hadith}`);
       console.log(`Translation: ${hadith.translation}`);
       console.log('---');
     });
@@ -43,15 +82,14 @@ getHadiths();
 
 ## Methods
 
-- getHadiths(book, maxLimits, options)
-
-- getQuranVerses(surah, verse, maxLimits, options)
-
-- getDuas(category, maxLimits, options)
-
-- searchHadith(query, book, maxLimits)
-
-- getBooks()
+- getHadiths({
+  book: 'Sahih al-Bukhari',
+  narrator: 'Abu Huraira (RA)',
+  category: 'prayer',
+  authenticity: 'Sahih',
+  language: 'English',
+  maxLimit: 3
+  })
 
 # Error Handling
 
@@ -61,8 +99,8 @@ try {
 } catch (error) {
   if (error.name === 'AuthenticationError') {
     console.log('Invalid API key');
-  } else if (error.name === 'RateLimitError') {
-    console.log('Rate limit exceeded');
+  } else if (error.name === 'InsufficientBalanceError') {
+    console.log('Insuffieient Balance');
   }
 }
 ```

package/dist/client.js

@@ -2,20 +2,20 @@ const axios = require('axios');
 const {
   DeenAPIError,
   AuthenticationError,
+  InsufficientBalanceError,
   RateLimitError,
   NotFoundError,
-  ServerError
+  ServerError,
+  ValidationError
 } = require('./exceptions');
 const {
   Hadith,
-  QuranVerse,
-  Dua,
   APIResponse
 } = require('./models');
 class ImaniroDeenAPIClient {
   constructor(apiKey, baseURL = 'https://deen-api.imaniro.com/api/v1') {
     if (!apiKey) {
-      throw new Error('API key is required');
+      throw new Error('API key is required. Get one at https://deen.imaniro.com/');
     }
     this.apiKey = apiKey;
     this.baseURL = baseURL.replace(/\/$/, '');
@@ -37,21 +37,25 @@ class ImaniroDeenAPIClient {
           data
         } = error.response;
         switch (status) {
+          case 400:
+            throw new ValidationError(data?.message || 'Invalid request parameters. See documentation at https://deen.imaniro.com/', status, data?.details);
           case 401:
-            throw new AuthenticationError(data?.message);
+            throw new AuthenticationError(data?.message || 'Invalid API key. Please check your API key at https://deen.imaniro.com/', status, data?.details);
+          case 402:
+            throw new InsufficientBalanceError(data?.message || 'Insufficient balance to process request. Please top up at https://deen.imaniro.com/', status, data?.details);
           case 404:
-            throw new NotFoundError(data?.message);
+            throw new NotFoundError(data?.message || 'Resource not found. Visit https://deen.imaniro.com/ for documentation', status, data?.details);
           case 429:
-            throw new RateLimitError(data?.message);
+            throw new RateLimitError(data?.message || 'Rate limit exceeded. Check your usage at https://deen.imaniro.com/', status, data?.details);
           case 500:
-            throw new ServerError(data?.message);
+            throw new ServerError(data?.message || 'Server error occurred. Please check status at https://deen.imaniro.com/', status, data?.details);
           default:
-            throw new DeenAPIError(data?.message || `HTTP Error: ${status}`, status);
+            throw new DeenAPIError(data?.message || `HTTP Error: ${status}. Visit https://deen.imaniro.com/ for assistance`, status, data?.details);
         }
       } else if (error.request) {
-        throw new DeenAPIError('Network error: Unable to connect to API');
+        throw new DeenAPIError('Network error: Unable to connect to API. Please check https://deen.imaniro.com/ for API status');
       } else {
-        throw new DeenAPIError(error.message);
+        throw new DeenAPIError(`${error.message}. Visit https://deen.imaniro.com/ for support`);
       }
     });
   }
@@ -63,14 +67,70 @@ class ImaniroDeenAPIClient {
       throw error;
     }
   }
-  async getHadiths(book, maxLimits = 10, options = {}) {
-    const params = {
-      book,
-      maxLimits,
-      ...options
-    };
+
+  /**
+   * Get hadiths based on specified criteria
+   *
+   * @param {Object} options - Search criteria options
+   * @param {string} [options.book] - Name of the hadith book (e.g., "Sahih al-Bukhari")
+   * @param {string} [options.hadithNumber] - Specific hadith number
+   * @param {string} [options.narrator] - Name of the narrator
+   * @param {string} [options.category] - Category or topic of the hadith (e.g., prayer, fasting)
+   * @param {string} [options.authenticity] - Classification of the hadith (e.g., Sahih, Daif)
+   * @param {string} [options.language="English"] - Language of the hadith (default: "English")
+   * @param {number} [options.maxLimit=1] - Maximum number of hadiths to return (default: 1, max: 500)
+   * @returns {Promise<Array<Hadith>>} List of Hadith objects matching the criteria
+   */
+  async getHadiths({
+    book,
+    hadithNumber,
+    narrator,
+    category,
+    authenticity,
+    language = 'English',
+    // Default to English
+    maxLimit = 1,
+    ...restOptions // For any additional options
+  } = {}) {
+    // Validate maxLimit
+    if (maxLimit > 500) {
+      throw new ValidationError('maxLimit cannot exceed 500. See API limits at https://deen.imaniro.com/');
+    }
+    if (maxLimit < 1) {
+      throw new ValidationError('maxLimit must be at least 1');
+    }
+
+    // Build params object - only include fields that are provided
+    const params = {};
+
+    // Add optional fields only if they have truthy values (not undefined, null, or empty string)
+    if (book) params.book = book;
+    if (hadithNumber) params.hadithNumber = hadithNumber;
+    if (narrator) params.narrator = narrator;
+    if (category) params.category = category;
+    if (authenticity) params.authenticity = authenticity;
+
+    // Always include language (with default) and maxLimit
+    params.language = language;
+    params.maxLimit = maxLimit;
+
+    // Add any additional options
+    Object.assign(params, restOptions);
     const response = await this._makeRequest('hadiths', params);
     return response.data.map(item => new Hadith(item));
   }
+
+  /**
+   * Check API status
+   * @returns {Promise<Object>} API status information
+   */
+  async checkStatus() {
+    try {
+      const response = await this.client.get('/status');
+      return response.data;
+    } catch (error) {
+      throw error;
+    }
+  }
 }
 module.exports = ImaniroDeenAPIClient;

package/dist/exceptions.js

@@ -1,36 +1,59 @@
 class DeenAPIError extends Error {
-  constructor(message, statusCode) {
+  constructor(message, statusCode, details = null) {
+    // Ensure message includes website reference if not already present
+    if (!message.includes('https://deen.imaniro.com/')) {
+      message = `${message} | For assistance, visit https://deen.imaniro.com/`;
+    }
     super(message);
     this.name = 'DeenAPIError';
     this.statusCode = statusCode;
+    this.details = details;
   }
 }
 class AuthenticationError extends DeenAPIError {
-  constructor(message = 'Invalid API key') {
-    super(message, 401);
+  constructor(message = 'Invalid API key. Please check your API key at https://deen.imaniro.com/', statusCode = 401, details = null) {
+    super(message, statusCode, details);
     this.name = 'AuthenticationError';
   }
 }
+class InsufficientBalanceError extends DeenAPIError {
+  constructor(message = 'Insufficient balance to process request. Please top up at https://deen.imaniro.com/', statusCode = 402, details = null) {
+    super(message, statusCode, details);
+    this.name = 'InsufficientBalanceError';
+  }
+}
+class ValidationError extends DeenAPIError {
+  constructor(message, statusCode = 400, details = null) {
+    // Ensure validation errors also include website reference
+    if (!message.includes('https://deen.imaniro.com/')) {
+      message = `${message} | See documentation at https://deen.imaniro.com/`;
+    }
+    super(message, statusCode, details);
+    this.name = 'ValidationError';
+  }
+}
 class RateLimitError extends DeenAPIError {
-  constructor(message = 'Rate limit exceeded') {
-    super(message, 429);
+  constructor(message = 'Rate limit exceeded. Check your usage at https://deen.imaniro.com/', statusCode = 429, details = null) {
+    super(message, statusCode, details);
     this.name = 'RateLimitError';
   }
 }
 class NotFoundError extends DeenAPIError {
-  constructor(message = 'Resource not found') {
-    super(message, 404);
+  constructor(message = 'Resource not found. Visit https://deen.imaniro.com/ for documentation', statusCode = 404, details = null) {
+    super(message, statusCode, details);
     this.name = 'NotFoundError';
   }
 }
 class ServerError extends DeenAPIError {
-  constructor(message = 'Server error occurred') {
-    super(message, 500);
+  constructor(message = 'Server error occurred. Please check status at https://deen.imaniro.com/', statusCode = 500, details = null) {
+    super(message, statusCode, details);
     this.name = 'ServerError';
   }
 }
 module.exports = {
   DeenAPIError,
+  InsufficientBalanceError,
+  ValidationError,
   AuthenticationError,
   RateLimitError,
   NotFoundError,

package/dist/index.js

@@ -6,6 +6,8 @@ const {
 const {
   DeenAPIError,
   AuthenticationError,
+  InsufficientBalanceError,
+  ValidationError,
   RateLimitError,
   NotFoundError,
   ServerError
@@ -16,6 +18,8 @@ module.exports = {
   APIResponse,
   DeenAPIError,
   AuthenticationError,
+  InsufficientBalanceError,
+  ValidationError,
   RateLimitError,
   NotFoundError,
   ServerError

package/dist/models.js

@@ -3,21 +3,44 @@ class Hadith {
     this.attribution = data.attribution || '';
     this.authenticity = data.authenticity || '';
     this.category = data.category || '';
-    this.context = data.context | '';
-    this.book = data.book || '';
-    this.number = data.number || '';
+    this.context = data.context || '';
     this.explanation = data.explanation || '';
     this.hadith = data.hadith || '';
     this.narratedBy = data.narratedBy || '';
+    this.book = data.book || '';
+    this.hadithId = data.hadithId || '';
+    this.number = data.number || '';
     this.translation = data.translation || '';
   }
+  toJSON() {
+    return {
+      attribution: this.attribution,
+      authenticity: this.authenticity,
+      category: this.category,
+      context: this.context,
+      explanation: this.explanation,
+      hadith: this.hadith,
+      narratedBy: this.narratedBy,
+      book: this.book,
+      hadithId: this.hadithId,
+      number: this.number,
+      translation: this.translation
+    };
+  }
 }
 class APIResponse {
   constructor(data) {
-    this.success = data.success || false;
-    this.data = data.data || [];
+    this.status = data.status || 'error';
     this.message = data.message || '';
-    this.count = data.count || 0;
+    this.data = data.data || [];
+    this.timestamp = data.timestamp ? new Date(data.timestamp) : new Date();
+    this.code = data.code || 200;
+  }
+  isSuccess() {
+    return this.status === 'success';
+  }
+  isError() {
+    return this.status === 'error';
   }
 }
 module.exports = {

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "deen-api-client",
-  "version": "1.0.0",
-  "description": "Node.js client for Deen API - Islamic resources API (Hadith, Quran, Duas)",
+  "version": "1.1.0",
+  "description": "Node.js client for Deen API - Retrieve Hadith, Quran (coming soon), and Duas (coming soon) with powerful filtering",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
+    "clean": "rm -rf dist/ lib/ node_modules/",
     "build": "babel src --out-dir dist",
     "prepublishOnly": "npm run build",
     "test": "jest",
@@ -27,7 +28,7 @@
     "type": "git",
     "url": "git+https://github.com/imaniro-tech/deen-api-js-client.git"
   },
-  "homepage": "https://github.com/imaniro-tech/deen-api-js-client",
+  "homepage": "https://deen.imaniro.com/documentation",
   "bugs": {
     "url": "https://github.com/imaniro-tech/deen-api-js-client/issues"
   },