@hadis-my/sdk

JavaScript/TypeScript SDK untuk API Hadis Malaysia - Akses 60,000+ hadis daripada 9 koleksi utama dalam Bahasa Arab dengan terjemahan Melayu dan Indonesia.

📦 Instalasi

npm install @hadis-my/sdk
# atau
yarn add @hadis-my/sdk
# atau
pnpm add @hadis-my/sdk

🚀 Quick Start

import { HadisClient } from '@hadis-my/sdk';

// Buat client dengan API key
const client = new HadisClient({
  apiKey: 'HADIS_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
});

// Dapatkan senarai koleksi
const { collections } = await client.getCollections();

// Dapatkan hadis dari Sahih Bukhari
const { hadis, meta } = await client.getHadisList('bukhari', {
  page: 1,
  perPage: 10
});

// Cari hadis
const { results } = await client.search('solat');

// Dapatkan hadis rawak
const { hadis: randomHadis } = await client.getRandom({ count: 5 });

📚 API Reference

HadisClient

Constructor

const client = new HadisClient({
  apiKey: 'HADIS_...', // Wajib
  baseUrl: 'https://service.hadis.my/api/v1', // Optional
  timeout: 30000 // Optional, dalam ms
});

Kaedah (Methods)

getCollections()

Dapatkan senarai semua koleksi hadis.

const { collections } = await client.getCollections();
// collections: Array<{ slug, name, author, total_hadis }>

getCollection(slug)

Dapatkan maklumat satu koleksi.

const { collection } = await client.getCollection('bukhari');

getHadisList(collection, options?)

Dapatkan senarai hadis dengan pagination.

const { hadis, meta } = await client.getHadisList('bukhari', {
  page: 1,
  perPage: 20,
  lang: 'ms' // 'ms' | 'id' | 'all'
});

getHadis(collection, id, lang?)

Dapatkan satu hadis berdasarkan ID.

const { hadis } = await client.getHadis('bukhari', 1);

search(query, options?)

Cari hadis berdasarkan kata kunci.

const { results, meta } = await client.search('solat', {
  collection: 'bukhari', // Optional
  lang: 'ms', // 'arab' | 'ms' | 'id' | 'all'
  page: 1,
  perPage: 20
});

getRandom(options?)

Dapatkan hadis secara rawak.

const { hadis } = await client.getRandom({
  collection: 'muslim', // Optional
  count: 5, // 1-10
  lang: 'ms'
});

🏛️ Koleksi Tersedia

| Slug | Nama | Jumlah Hadis | |------|------|--------------| | bukhari | Sahih Bukhari | 7,008 | | muslim | Sahih Muslim | 5,362 | | abu-daud | Sunan Abu Dawud | 4,590 | | tirmidzi | Sunan Tirmidzi | 3,891 | | nasai | Sunan An-Nasai | 5,662 | | ibnu-majah | Sunan Ibnu Majah | 4,332 | | ahmad | Musnad Ahmad | 26,363 | | malik | Muwatta Malik | 1,594 | | darimi | Sunan Ad-Darimi | 3,367 |

⚠️ Error Handling

import { HadisApiError, RateLimitError } from '@hadis-my/sdk';

try {
  const { hadis } = await client.getHadis('bukhari', 999999);
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limit hit: ${error.limitType}`);
    console.log(`Retry after: ${error.retryAfter} seconds`);
  } else if (error instanceof HadisApiError) {
    console.log(`Error: ${error.message}`);
    console.log(`Code: ${error.code}`);
    console.log(`Status: ${error.status}`);
  }
}

📄 TypeScript Support

SDK ini ditulis sepenuhnya dalam TypeScript. Semua types tersedia:

import type {
  HadisClientConfig,
  Collection,
  Hadis,
  CollectionSlug,
  Language,
  PaginationMeta
} from '@hadis-my/sdk';

🔗 Links

• Dokumentasi Penuh
• Dapatkan API Key
• API Reference

📝 License

ISC © Dayabumi Creative Network