sholawat-json 0.3.2 → 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.2",
+  "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": {

package/sholawat/sholawat.json

@@ -75,7 +75,14 @@
                     "7.json",
                     "8.json",
                     "9.json",
-                    "10.json"
+                    "10.json",
+                    "11.json",
+                    "12.json",
+                    "13.json",
+                    "14.json",
+                    "15.json",
+                    "16.json",
+                    "17.json"
                 ],
                 "schema": "simtudduror_fasl_v1.0.schema.json"
             }

package/PUBLISHING.md

@@ -1,190 +0,0 @@
-# Publishing Guide
-
-## How Publishing Works
-
-This project automatically publishes to **npm** when you create a GitHub release. Once published to npm, **jsDelivr** automatically mirrors the package within minutes.
-
-### Distribution Chain
-```
-GitHub Release → npm → jsDelivr CDN
-```
-
-## Quick Start: Publishing a New Version
-
-1. **Make your changes** and ensure they pass validation
-2. **Create a GitHub release**:
-   - Go to https://github.com/afaf-tech/sholawat-json/releases/new
-   - Choose a version tag (e.g., `v0.3.2` or `0.3.2`)
-   - Write release notes
-   - Click "Publish release"
-3. **Automated workflow runs**:
-   - ✅ Validates all JSON files
-   - ✅ Updates `package.json` version
-   - ✅ Publishes to npm
-4. **Wait ~5 minutes** for jsDelivr to pick up the new version
-
-## Prerequisites (One-Time Setup)
-
-### 1. Create npm Account
-If you don't have one: https://www.npmjs.com/signup
-
-### 2. Get npm Access Token
-1. Log in to npm: https://www.npmjs.com/
-2. Click your profile → "Access Tokens"
-3. Click "Generate New Token" → "Classic Token"
-4. Select **Automation** type
-5. Copy the token (starts with `npm_...`)
-
-### 3. Add Token to GitHub
-1. Go to: https://github.com/afaf-tech/sholawat-json/settings/secrets/actions
-2. Click "New repository secret"
-3. Name: `NPM_TOKEN`
-4. Value: Paste your npm token
-5. Click "Add secret"
-
-## Version Numbering
-
-Follow [Semantic Versioning](https://semver.org/):
-
-- **Patch** (e.g., `0.3.1` → `0.3.2`): Bug fixes, typo corrections
-- **Minor** (e.g., `0.3.1` → `0.4.0`): New content, new translations, backwards-compatible
-- **Major** (e.g., `0.3.1` → `1.0.0`): Breaking changes to JSON structure/schema
-
-## Creating a Release
-
-### Via GitHub Web Interface
-
-1. Go to: https://github.com/afaf-tech/sholawat-json/releases/new
-2. **Tag version**: Enter version (e.g., `v0.3.2` or `0.3.2`)
-3. **Target**: Keep as `master`
-4. **Release title**: Same as tag (e.g., `v0.3.2`)
-5. **Description**: Summarize changes:
-   ```markdown
-   ## What's New
-   - Added Indonesian translation for Burdah Fasl 10
-   - Fixed typo in Simtudduror Fasl 5
-   
-   ## Files Changed
-   - sholawat/burdah/nu_online/fasl/10.json
-   - sholawat/simtudduror/nu_online/fasl/5.json
-   ```
-6. Click **"Publish release"**
-
-### Via Command Line (Alternative)
-
-```bash
-# Tag the current commit
-git tag v0.3.2
-
-# Push the tag
-git push origin v0.3.2
-
-# Then create release on GitHub using the tag
-```
-
-## What Happens During Publish
-
-1. **GitHub Actions triggers** (`.github/workflows/publish.yml`)
-2. **Validation runs** using Go validator
-   - If validation fails, publish stops
-3. **Version updated** in `package.json` based on release tag
-4. **Published to npm** with provenance attestation
-5. **jsDelivr mirrors** automatically within 5-10 minutes
-
-## Verifying Publication
-
-### Check npm
-```bash
-npm view sholawat-json version
-```
-
-Or visit: https://www.npmjs.com/package/sholawat-json
-
-### Check jsDelivr
-- Latest version: https://cdn.jsdelivr.net/npm/sholawat-json@latest/sholawat/sholawat.json
-- Specific version: https://cdn.jsdelivr.net/npm/sholawat-json@0.3.2/sholawat/sholawat.json
-- Purge cache: https://www.jsdelivr.com/tools/purge
-
-## Manual Publishing (Fallback)
-
-If automated workflow fails:
-
-```bash
-# 1. Validate locally
-cd validator
-go run main.go
-
-# 2. Update version in package.json
-npm version patch  # or minor, major
-
-# 3. Login to npm (one time)
-npm login
-
-# 4. Publish
-npm publish --access public
-```
-
-## Continuous Integration
-
-### Validation Workflow (`.github/workflows/validate.yml`)
-
-Runs on every push/PR to master that modifies JSON files:
-- ✅ Validates all JSON against schemas
-- ✅ Prevents invalid data from being merged
-- ✅ Ensures data integrity before release
-
-### When Validation Fails
-
-1. Check the Actions tab: https://github.com/afaf-tech/sholawat-json/actions
-2. Click the failed workflow run
-3. Read the error messages from validator
-4. Fix the JSON files
-5. Commit and push fixes
-
-## Best Practices
-
-1. **Always validate locally** before pushing:
-   ```bash
-   cd validator && go run main.go
-   ```
-
-2. **Test changes** in a branch before merging to master
-
-3. **Write clear release notes** describing what changed
-
-4. **Use semantic versioning** consistently
-
-5. **Don't delete releases** - users may depend on specific versions
-
-6. **Update sholawat.json** when adding new files or sources
-
-## Troubleshooting
-
-### "NPM_TOKEN not found"
-- Ensure the secret is added in repository settings
-- Name must be exactly `NPM_TOKEN`
-
-### "Validation failed"
-- Run `cd validator && go run main.go` locally
-- Fix reported schema violations
-- Commit fixes and re-release
-
-### "Permission denied" when publishing
-- Verify npm token has correct permissions
-- Ensure you're a maintainer on npm package
-
-### jsDelivr shows old version
-- Wait 5-10 minutes for CDN propagation
-- Force purge: https://www.jsdelivr.com/tools/purge
-- Use specific version URL instead of `@latest`
-
-## Resources
-
-- npm package: https://www.npmjs.com/package/sholawat-json
-- jsDelivr CDN: https://www.jsdelivr.com/package/npm/sholawat-json
-- GitHub Actions: https://github.com/afaf-tech/sholawat-json/actions
-- Semantic Versioning: https://semver.org/
-
-## Questions?
-
-Open an issue: https://github.com/afaf-tech/sholawat-json/issues