sholawat-json 0.3.1 → 0.3.3

package/README.md

@@ -6,35 +6,302 @@ All praise is due to Allah SWT for His countless blessings. May blessings and pe
 
 We strive for accuracy, but if you encounter any errors, please reach out. Your feedback is invaluable for improvement.
 
-## CDN
-Check out the [`/sholawat`](https://github.com/afaf-tech/sholawat-json/tree/master/sholawat) to see all available sholawat and source files. The JSON files are also available through [JSDELIVER](https://www.jsdelivr.com/package/npm/sholawat-json) CDN
+## 🚀 Quick Start
 
-### List Sholawat and Sources 
-get the information with : 
+### Option 1: CDN (Recommended for Web Projects)
+
+No installation needed! Just fetch directly from jsDelivr CDN:
+
+```javascript
+// Fetch list of all available sholawat
+fetch('https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/sholawat.json')
+  .then(response => response.json())
+  .then(data => console.log(data));
+```
+
+### Option 2: npm Package
+
+```bash
+npm install sholawat-json
+```
+
+Then import in your project:
+
+```javascript
+import sholawatList from 'sholawat-json/sholawat/sholawat.json';
+import burdahFasl1 from 'sholawat-json/sholawat/burdah/nu_online/fasl/1.json';
+```
+
+---
+
+## 📖 Usage Guide
+
+### Step 1: Get Available Sholawat
+
+First, fetch the master list to see all available sholawat, sources, and file paths:
+
+**Endpoint:**
 ```
 https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/sholawat.json
 ```
-### Get a Fasl
 
-You can get a single chapter (fasl) by providing its faslNumber for each sholawat. Text, transliteration and translation are provided on each fasl. To get it you can provide: 
+**Example Response:**
+```json
+[
+  {
+    "name": "burdah",
+    "sources": [
+      {
+        "source_name": "nu online",
+        "description": "burdah-fasl",
+        "path_files": "sholawat/burdah/nu_online/fasl/",
+        "files": ["1.json", "2.json", "3.json", ...],
+        "schema": "burdah_fasl_v1.0.schema.json"
+      }
+    ]
+  }
+]
+```
+
+### Step 2: Fetch Specific Sholawat Content
+
+#### For Fasl-based Sholawat (Burdah, Diba, Simtudduror)
+
+**URL Pattern:**
+```
+https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/{name}/{source}/fasl/{number}.json
+```
+
+**Examples:**
+
+```javascript
+// Fetch Burdah Fasl 1 from NU Online
+const burdahUrl = 'https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/burdah/nu_online/fasl/1.json';
+
+// Fetch Diba Fasl 10 from NU Online
+const dibaUrl = 'https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/diba/nu_online/fasl/10.json';
+
+// Fetch Simtudduror Fasl 5
+const simtuddurorUrl = 'https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/simtudduror/nu_online/fasl/5.json';
+```
+
+#### For Single Sholawat (Tunggal & Suluk)
+
+**URL Pattern:**
+```
+https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/{type}/{filename}.json
 ```
-https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/{sholawatName}/{source}/fasl/{faslNumber}.json
 
+**Examples:**
+
+```javascript
+// Fetch a tunggal sholawat
+const tunggalUrl = 'https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/tunggal/assalamu-alaika-zainal-anbiya.json';
+
+// Fetch a suluk sholawat
+const sulukUrl = 'https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/suluk/hubbun-nabi.json';
 ```
-For Example:
 
-- Sholawat Diba from nu online fasl 1: `https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/diba/nu_online/fasl/10.json`
+---
 
-Get a Schema
-You can access the JSON schema for each fasl in the schemas folder. These schemas ensure the data structure remains consistent and reliable. Use the following link to get the schema:
+## 💻 Code Examples
 
-```bash
+### Vanilla JavaScript (Fetch API)
+
+```javascript
+async function getSholawat() {
+  try {
+    const response = await fetch(
+      'https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/burdah/nu_online/fasl/1.json'
+    );
+    const data = await response.json();
+    
+    console.log('Sholawat Name:', data.name);
+    console.log('Arabic Text:', data.text);
+    console.log('Translation:', data.translations.id.name);
+  } catch (error) {
+    console.error('Error fetching sholawat:', error);
+  }
+}
+
+getSholawat();
+```
+
+### React Example
+
+```jsx
+import React, { useState, useEffect } from 'react';
+
+function SholawatDisplay() {
+  const [sholawat, setSholawat] = useState(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/diba/nu_online/fasl/1.json')
+      .then(res => res.json())
+      .then(data => {
+        setSholawat(data);
+        setLoading(false);
+      })
+      .catch(err => console.error(err));
+  }, []);
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h2>{sholawat.name}</h2>
+      <div>
+        {Object.entries(sholawat.text).map(([key, verse]) => (
+          <div key={key}>
+            <p className="arabic">{verse.arabic}</p>
+            <p className="latin">{verse.latin}</p>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Vue.js Example
+
+```vue
+<template>
+  <div v-if="sholawat">
+    <h2>{{ sholawat.name }}</h2>
+    <div v-for="(verse, key) in sholawat.text" :key="key">
+      <p class="arabic">{{ verse.arabic }}</p>
+      <p class="latin">{{ verse.latin }}</p>
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      sholawat: null
+    };
+  },
+  mounted() {
+    fetch('https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/burdah/nu_online/fasl/1.json')
+      .then(res => res.json())
+      .then(data => this.sholawat = data);
+  }
+};
+</script>
+```
+
+### Axios Example
+
+```javascript
+import axios from 'axios';
+
+const API_BASE = 'https://cdn.jsdelivr.net/npm/sholawat-json@latest';
+
+// Get all sholawat list
+const getAllSholawat = () => 
+  axios.get(`${API_BASE}/sholawat/sholawat.json`);
+
+// Get specific fasl
+const getBurdahFasl = (number) => 
+  axios.get(`${API_BASE}/sholawat/burdah/nu_online/fasl/${number}.json`);
+
+// Usage
+getAllSholawat()
+  .then(response => console.log(response.data))
+  .catch(error => console.error(error));
+
+getBurdahFasl(1)
+  .then(response => console.log(response.data))
+  .catch(error => console.error(error));
+```
+
+---
+
+## 📦 Data Structure
+
+### Fasl-based Sholawat (Burdah, Diba, Simtudduror)
+
+```json
+{
+  "number": 1,
+  "source": "nu_online",
+  "name": "بَانَتْ سُعَادُ",
+  "text": {
+    "1": {
+      "arabic": "بَانَتْ سُعَادُ فَقَلْبِيْ الْيَوْمَ مَتْبُوْلُ",
+      "latin": "Bānat Su'ādu faqalbil yauma matbūlu"
+    }
+  },
+  "translations": {
+    "id": {
+      "name": "Suad Telah Pergi",
+      "text": {
+        "1": "Suad telah pergi, maka hatiku hari ini terguncang"
+      }
+    }
+  },
+  "last_updated": "2024-06-15"
+}
+```
+
+### Single Sholawat (Tunggal & Suluk)
+
+```json
+{
+  "source": "general",
+  "name": "يَا سَيِّدِيْ يَا رَسُوْلَ اللهِ",
+  "latin": "Ya Sayyidi Ya Rasulallah",
+  "text": {
+    "1": {
+      "arabic": "يَا سَيِّدِيْ يَا رَسُوْلَ اللهِ",
+      "latin": "Yā sayyidī yā rasūlallāh"
+    }
+  },
+  "translations": {
+    "id": {
+      "name": "Ya Tuanku Ya Rasulullah",
+      "translator": "Tim NU Online",
+      "text": {
+        "1": "Wahai tuanku wahai Rasulullah"
+      }
+    }
+  },
+  "last_updated": "2024-07-04"
+}
+```
+
+---
+
+## 🔍 Schema Validation
+
+Each sholawat type follows a JSON Schema for data consistency. You can access schemas at:
+
+```
 https://cdn.jsdelivr.net/npm/sholawat-json@latest/schemas/{schema_name}.schema.json
 ```
-For example:
 
-Burdah Fasl Schema (v1.0):
-https://cdn.jsdelivr.net/npm/sholawat-json@latest/schemas/burdah_fasl_v1.0.schema.json
+**Available Schemas:**
+- `burdah_fasl_v1.0.schema.json` - Burdah chapters
+- `diba_fasl_v1.0.schema.json` - Diba chapters  
+- `simtudduror_fasl_v1.0.schema.json` - Simtudduror chapters
+- `sholawat_tunggal_v1.0.schema.json` - Single sholawat
+- `suluk_v1.0.schema.json` - Suluk sholawat
+
+**Example:**
+```javascript
+const schemaUrl = 'https://cdn.jsdelivr.net/npm/sholawat-json@latest/schemas/burdah_fasl_v1.0.schema.json';
+```
+
+---
+
+## 🗂️ Browse Files
+
+Explore all available sholawat files in the repository:
+- [Browse `/sholawat` directory](https://github.com/afaf-tech/sholawat-json/tree/master/sholawat)
+- [View on jsDelivr CDN](https://www.jsdelivr.com/package/npm/sholawat-json)
 
 ## Data Sources
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sholawat-json",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "All praise is due to Allah SWT for His countless blessings. May blessings and peace always be upon our beloved Prophet Muhammad SAW.",
   "main": "index.js",
   "scripts": {
@@ -16,7 +16,9 @@
     "sholawat",
     "sholawat-json",
     "majlis",
-    "diba", "burdah", "simtudduror"
+    "diba",
+    "burdah",
+    "simtudduror"
   ],
   "author": "afaf-tech",
   "license": "MIT",

package/schemas/sholawat_tunggal_v1.0.schema.json

@@ -0,0 +1,101 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Sholawat Tunggal Schema",
+    "version": "1.0",
+    "type": "object",
+    "properties": {
+        "source": {
+            "type": "string",
+            "description": "The source of the text."
+        },
+        "name": {
+            "type": "string",
+            "description": "The Arabic name of the sholawat."
+        },
+        "latin": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "description": "The transliteration of the sholawat name."
+        },
+        "text": {
+            "type": "object",
+            "description": "Contains the Arabic text and its transliteration.",
+            "patternProperties": {
+                "^[0-9]+$": {
+                    "type": "object",
+                    "properties": {
+                        "arabic": {
+                            "type": "string",
+                            "description": "The Arabic text of the verse."
+                        },
+                        "latin": {
+                            "type": [
+                                "string",
+                                "null"
+                            ],
+                            "description": "The transliteration of the Arabic text."
+                        }
+                    },
+                    "required": [
+                        "arabic"
+                    ],
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "translations": {
+            "type": [
+                "object",
+                "null"
+            ],
+            "description": "Translations in various languages.",
+            "patternProperties": {
+                "^[a-z]{2}$": {
+                    "type": "object",
+                    "description": "The key representing the language code using a two-letter ISO 639-1 code (e.g., 'en' for English, 'id' for Indonesian).",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "The translated name of the sholawat in the specified language."
+                        },
+                        "translator": {
+                            "type": "string",
+                            "description": "Translator of the sholawat."
+                        },
+                        "text": {
+                            "type": "object",
+                            "description": "Translated text for each verse in the specified language.",
+                            "patternProperties": {
+                                "^[0-9]+$": {
+                                    "type": "string",
+                                    "description": "Translated text of the verse in the specified language."
+                                }
+                            },
+                            "additionalProperties": false
+                        }
+                    },
+                    "required": [
+                        "name",
+                        "text"
+                    ],
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "last_updated": {
+            "type": "string",
+            "format": "date",
+            "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$",
+            "description": "The date when the content was last updated, in YYYY-MM-DD format."
+        }
+    },
+    "required": [
+        "name",
+        "text"
+    ],
+    "additionalProperties": false
+}

package/schemas/sholawat_tunggal_v1.1.schema.json

@@ -0,0 +1,118 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Sholawat Tunggal Schema",
+    "version": "1.1",
+    "type": "object",
+    "properties": {
+        "source": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "description": "The source of the text."
+        },
+        "author": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "description": "The author of the sholawat."
+        },
+        "transmitter": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "description": "The transmitter or narrator of the sholawat."
+        },
+        "name": {
+            "type": "string",
+            "description": "The Arabic name of the sholawat."
+        },
+        "latin": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "description": "The transliteration of the sholawat name."
+        },
+        "text": {
+            "type": "object",
+            "description": "Contains the Arabic text and its transliteration.",
+            "patternProperties": {
+                "^[0-9]+$": {
+                    "type": "object",
+                    "properties": {
+                        "arabic": {
+                            "type": "string",
+                            "description": "The Arabic text of the verse."
+                        },
+                        "latin": {
+                            "type": [
+                                "string",
+                                "null"
+                            ],
+                            "description": "The transliteration of the Arabic text."
+                        }
+                    },
+                    "required": [
+                        "arabic"
+                    ],
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "translations": {
+            "type": [
+                "object",
+                "null"
+            ],
+            "description": "Translations in various languages.",
+            "patternProperties": {
+                "^[a-z]{2}$": {
+                    "type": "object",
+                    "description": "The key representing the language code using a two-letter ISO 639-1 code (e.g., 'en' for English, 'id' for Indonesian).",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "The translated name of the sholawat in the specified language."
+                        },
+                        "translator": {
+                            "type": "string",
+                            "description": "Translator of the sholawat."
+                        },
+                        "text": {
+                            "type": "object",
+                            "description": "Translated text for each verse in the specified language.",
+                            "patternProperties": {
+                                "^[0-9]+$": {
+                                    "type": "string",
+                                    "description": "Translated text of the verse in the specified language."
+                                }
+                            },
+                            "additionalProperties": false
+                        }
+                    },
+                    "required": [
+                        "name",
+                        "text"
+                    ],
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "last_updated": {
+            "type": "string",
+            "format": "date",
+            "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$",
+            "description": "The date when the content was last updated, in YYYY-MM-DD format."
+        }
+    },
+    "required": [
+        "name",
+        "text"
+    ],
+    "additionalProperties": false
+}

package/schemas/suluk_v1.0.schema.json

@@ -0,0 +1,101 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "title": "Suluk Schema",
+    "version": "1.0",
+    "type": "object",
+    "properties": {
+        "source": {
+            "type": "string",
+            "description": "The source of the text."
+        },
+        "name": {
+            "type": "string",
+            "description": "The Arabic name of the suluk."
+        },
+        "latin": {
+            "type": [
+                "string",
+                "null"
+            ],
+            "description": "The transliteration of the suluk name."
+        },
+        "text": {
+            "type": "object",
+            "description": "Contains the Arabic text and its transliteration.",
+            "patternProperties": {
+                "^[0-9]+$": {
+                    "type": "object",
+                    "properties": {
+                        "arabic": {
+                            "type": "string",
+                            "description": "The Arabic text of the verse."
+                        },
+                        "latin": {
+                            "type": [
+                                "string",
+                                "null"
+                            ],
+                            "description": "The transliteration of the Arabic text."
+                        }
+                    },
+                    "required": [
+                        "arabic"
+                    ],
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "translations": {
+            "type": [
+                "object",
+                "null"
+            ],
+            "description": "Translations in various languages.",
+            "patternProperties": {
+                "^[a-z]{2}$": {
+                    "type": "object",
+                    "description": "The key representing the language code using a two-letter ISO 639-1 code (e.g., 'en' for English, 'id' for Indonesian).",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "description": "The translated name of the suluk in the specified language."
+                        },
+                        "translator": {
+                            "type": "string",
+                            "description": "Translator of the suluk."
+                        },
+                        "text": {
+                            "type": "object",
+                            "description": "Translated text for each verse in the specified language.",
+                            "patternProperties": {
+                                "^[0-9]+$": {
+                                    "type": "string",
+                                    "description": "Translated text of the verse in the specified language."
+                                }
+                            },
+                            "additionalProperties": false
+                        }
+                    },
+                    "required": [
+                        "name",
+                        "text"
+                    ],
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        },
+        "last_updated": {
+            "type": "string",
+            "format": "date",
+            "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$",
+            "description": "The date when the content was last updated, in YYYY-MM-DD format."
+        }
+    },
+    "required": [
+        "name",
+        "text"
+    ],
+    "additionalProperties": false
+}