cloudku-murotal/README.md

JavaScript client for Murotal API - Islamic prayer times, Quran, Hadith, and Dua

# 🕌 Murotal API Client

<div align="center">

![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933?style=for-the-badge&logo=node.js&logoColor=white)
![NPM](https://img.shields.io/badge/NPM-CB3837?style=for-the-badge&logo=npm&logoColor=white)
![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black)
![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
![MIT License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)

**Modern Islamic API Client - Simple, Fast, Reliable**

✨ **Created by [AlfiDev](https://github.com/cloudkuimages)**

[📦 Install](#-installation) • [🚀 Quick Start](#-quick-start) • [📖 Documentation](#-api-reference) • [💡 Examples](#-examples)

</div>

---

## 🌟 Features

<div align="center">

| 🕌 **Prayer Times** | 📖 **Al-Quran** | 🤲 **Dua & Hadith** | 📅 **Calendar** |
|:---:|:---:|:---:|:---:|
| Jadwal sholat akurat | Surah & Ayat lengkap | Koleksi doa harian | Kalender Hijriah |
| Multi-kota Indonesia | Audio murotal | Hadist Bukhari | Konversi tanggal |
| Update real-time | Terjemahan & tafsir | Hadist Arbain | Event Islam |

</div>

---

## 📦 Installation

```bash
npm install cloudku-murotal
```

```bash
yarn add cloudku-murotal
```

---

## 🚀 Quick Start

```javascript
import MurotalAPI from 'cloudku-murotal';
const api = new MurotalAPI();

const prayer = await api.getPrayerTimes('1', '2024-01-01');
const ayah = await api.getRandomAyah();
const doa = await api.getRandomDoa();
```

<details>
<summary>📋 Click to see response examples</summary>

```javascript
{
  jadwal: {
    tanggal: '2024-01-01',
    imsak: '04:30',
    subuh: '04:40',
    terbit: '06:05',
    dhuha: '06:30',
    dzuhur: '12:10',
    ashar: '15:25',
    maghrib: '18:15',
    isya: '19:30'
  }
}
```

</details>

---

## 🎯 Usage Methods

### 🔧 ES Modules (Recommended)
```javascript
import MurotalAPI from 'cloudku-murotal';
const api = new MurotalAPI();
```

### 📦 CommonJS
```javascript
const { MurotalAPI } = require('cloudku-murotal');
const api = new MurotalAPI();
```

### 🌐 Browser
```html
<script type="module">
import MurotalAPI from './node_modules/cloudku-murotal/index.mjs';
const api = new MurotalAPI();
</script>
```

---

## 📖 API Reference

### 🕌 Prayer Times & Location

<table>
<tr><th>Method</th><th>Parameters</th><th>Description</th></tr>
<tr><td><code>getCities()</code></td><td>-</td><td>📍 List semua kota Indonesia</td></tr>
<tr><td><code>searchCities(query)</code></td><td>string</td><td>🔍 Cari kota berdasarkan nama</td></tr>
<tr><td><code>getPrayerTimes(id, date)</code></td><td>string, string</td><td>⏰ Jadwal sholat harian</td></tr>
<tr><td><code>getPrayerTimesByMonth(id, month, year)</code></td><td>string, number, number</td><td>📅 Jadwal sholat bulanan</td></tr>
</table>

### 📅 Islamic Calendar

<table>
<tr><th>Method</th><th>Parameters</th><th>Description</th></tr>
<tr><td><code>getTodayHijriDate()</code></td><td>-</td><td>📆 Tanggal Hijriah hari ini</td></tr>
<tr><td><code>getHijriDate(date)</code></td><td>string</td><td>🔄 Konversi Masehi ke Hijriah</td></tr>
</table>

### 🌟 Asmaul Husna

<table>
<tr><th>Method</th><th>Parameters</th><th>Description</th></tr>
<tr><td><code>getAllHusna()</code></td><td>-</td><td>📜 99 Asmaul Husna lengkap</td></tr>
<tr><td><code>getRandomHusna()</code></td><td>-</td><td>🎲 Asmaul Husna acak</td></tr>
<tr><td><code>getHusnaByNumber(id)</code></td><td>number</td><td>🔢 Berdasarkan urutan 1-99</td></tr>
</table>

### 📖 Holy Quran

<table>
<tr><th>Method</th><th>Parameters</th><th>Description</th></tr>
<tr><td><code>getSurahList()</code></td><td>-</td><td>📋 114 Surah Al-Quran</td></tr>
<tr><td><code>getSurahByNumber(id)</code></td><td>number</td><td>📖 Surah berdasarkan nomor</td></tr>
<tr><td><code>getRandomSurah()</code></td><td>-</td><td>🎲 Surah acak</td></tr>
<tr><td><code>getAyahByNumber(id)</code></td><td>number</td><td>📝 Ayat berdasarkan nomor global</td></tr>
<tr><td><code>getSingleAyah(surat, ayat)</code></td><td>number, number</td><td>🎯 Ayat spesifik</td></tr>
<tr><td><code>getAyahRange(surat, start, end)</code></td><td>number, number, number</td><td>📏 Range ayat dalam surah</td></tr>
<tr><td><code>getJuz(id)</code></td><td>number</td><td>📚 Juz 1-30</td></tr>
<tr><td><code>getRandomAyah()</code></td><td>-</td><td>🎲 Ayat acak</td></tr>
<tr><td><code>getAllThemes()</code></td><td>-</td><td>🏷️ Tema-tema Al-Quran</td></tr>
<tr><td><code>getAyahByTheme(id)</code></td><td>number</td><td>📑 Ayat berdasarkan tema</td></tr>
</table>

### 🤲 Prayers & Hadith

<table>
<tr><th>Method</th><th>Parameters</th><th>Description</th></tr>
<tr><td><code>getDoaSources()</code></td><td>-</td><td>📚 Sumber-sumber doa</td></tr>
<tr><td><code>searchDoa(query)</code></td><td>string</td><td>🔍 Cari doa berdasarkan kata kunci</td></tr>
<tr><td><code>getRandomDoa()</code></td><td>-</td><td>🎲 Doa acak</td></tr>
<tr><td><code>getRandomHadistArbain()</code></td><td>-</td><td>🎲 Hadist Arbain acak</td></tr>
<tr><td><code>getRandomHadistBukhari()</code></td><td>-</td><td>🎲 Hadist Bukhari acak</td></tr>
</table>

---

## 💡 Examples

### 🏙️ Get Prayer Times for Jakarta
```javascript
const cities = await api.getCities();
const jakartaId = cities.find(city => city.lokasi === 'Jakarta').id;
const todayPrayer = await api.getPrayerTimes(jakartaId, '2024-01-01');
```

### 📖 Read Random Quran Verse
```javascript
const randomAyah = await api.getRandomAyah();
console.log(`${randomAyah.surat.nama} - Ayat ${randomAyah.nomor_ayat}`);
console.log(randomAyah.ar);
console.log(randomAyah.tr);
```

### 🤲 Daily Prayer Collection
```javascript
const morningPrayer = await api.searchDoa('pagi');
const randomDua = await api.getRandomDoa();
const hadith = await api.getRandomHadistBukhari();
```

### 📅 Islamic Calendar Integration
```javascript
const hijriToday = await api.getTodayHijriDate();
const convertedDate = await api.getHijriDate('2024-01-01');
console.log(`Today in Hijri: ${hijriToday.hijri}`);
```

### 🌟 Asmaul Husna Display
```javascript
const allNames = await api.getAllHusna();
const randomName = await api.getRandomHusna();
const specificName = await api.getHusnaByNumber(1);
```

### ⚙️ Custom Configuration
```javascript
const api = new MurotalAPI('https://cloudku.us.kg');
```

---

## 🛡️ Error Handling

```javascript
try {
  const result = await api.getPrayerTimes('1', '2024-01-01');
  console.log('✅ Success:', result);
} catch (error) {
  console.error('❌ API Error:', error.message);
  
  if (error.code === 'NETWORK_ERROR') {
    console.log('🔄 Retrying in 5 seconds...');
  }
}
```

---

## 🔧 Requirements

<div align="center">

| Environment | Version | Status |
|:---:|:---:|:---:|
| **Node.js** | 20+ | ✅ Supported |
| **Browser** | ES6+ | ✅ Supported |
| **TypeScript** | 4.5+ | ✅ Compatible |

</div>

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

---

## 📊 Project Stats

<div align="center">

![GitHub stars](https://img.shields.io/github/stars/cloudkuimages/cloudku-murotal-api?style=social)
![GitHub forks](https://img.shields.io/github/forks/cloudkuimages/cloudku-murotal-api?style=social)
![NPM downloads](https://img.shields.io/npm/dt/cloudku-murotal?style=social&logo=npm)

</div>

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

<div align="center">

**🔗 Quick Links**

[![GitHub](https://img.shields.io/badge/GitHub-Repository-181717?style=for-the-badge&logo=github)](https://github.com/cloudkuimages)
[![NPM](https://img.shields.io/badge/NPM-Package-CB3837?style=for-the-badge&logo=npm)](https://npmjs.com/package/cloudku-murotal)
[![Documentation](https://img.shields.io/badge/Docs-API_Reference-blue?style=for-the-badge&logo=gitbook)](https://github.com/cloudkuimages)

**Made with ❤️ by [AlfiDev](https://github.com/cloudkuimages)**

*Bringing Islamic resources to developers worldwide* 🌍

</div>

---

## 🎯 Roadmap

- [ ] TypeScript definitions
- [ ] GraphQL support
- [ ] Offline caching
- [ ] React hooks package
- [ ] Vue.js plugin
- [ ] CLI tool
- [ ] WebSocket real-time updates

---

<div align="center">

*If this package helps your project, please consider giving it a ⭐ on GitHub!*

</div>