quran-api-unified

العربية · English

مكتبة JavaScript/TypeScript تُوحِّد الوصول إلى مصادر القرآن الكريم المتعددة — النصّ، والصوت، والترجمة، والتفسير — خلف واجهةٍ واحدة وبنية بيانات موحّدة، مع اختيارٍ تلقائيّ للمزوّد وتبديلٍ احتياطيّ عند تعذُّره؛ فلا يبقى تطبيقك رهينةً لمصدرٍ واحد.

ما قبل الإصدار. المكتبة مُنجَزة وتجتاز مجموعة اختباراتها كاملةً عبر أنواع المحتوى الأربعة، ولم تُنشر بعدُ على npm.

ما هذه المكتبة؟

عند بناء تطبيقات القرآن الكريم يواجه المطوّرون تشتُّت المصادر: فمصدرٌ يُرجِع الآيات في حقلٍ باسم verses، وآخر باسم ayahs، ببنيةٍ مختلفة تمامًا، وثالثٌ مخصَّصٌ للصوت وحده، ورابعٌ للترجمة. هذا التشتُّت يربط تطبيقك بمصدرٍ بعينه؛ فإذا تعطّل — كما يحدث في مواسم الذروة — اضطُررت إلى إعادة كتابة أجزاء من واجهتك.

تعمل هذه المكتبة طبقةَ توحيدٍ تجلس بين تطبيقك وبين تلك المصادر: تأخذ البيانات الخام من أيّ مزوّدٍ متاح، وتُحوّلها إلى بنيةٍ واحدة ثابتة تحدِّدها أنت، وتُعيدها إليك. تسأل عن آيةٍ أو سورة، وتطلب ما تشاء معها من صوتٍ أو ترجمةٍ أو تفسير، فتحصل على كلّ ذلك في استدعاءٍ واحد، بالشكل نفسه مهما تغيّر المصدر.

المميزات

• واجهة واحدة لعدّة مصادر، ولا يعنيك أيُّها خدَم الطلب.
• بنية موحّدة لكلّ نوعٍ من المحتوى: النصّ، والصوت، والترجمة، والتفسير.
• تبديل احتياطيّ تلقائيّ: إذا سقط مصدرٌ انتقلت المكتبة إلى البديل، وتُسجّل لك مسار المحاولات.
• طلبٌ واحدٌ يجمع كلّ شيء: آيةٌ أو سورةٌ مع صوتها وترجمتها وتفسيرها في استدعاءٍ واحد، ولو جاء كلٌّ منها من مصدرٍ مختلف.
• نظام مُحوّلات قابل للتوسعة: لكلّ مزوّدٍ مُحوّلٌ خاصّ، ويمكنك تسجيل مُحوّلك أنت.
• يعمل دون مفاتيح افتراضيًا، مع دعمٍ اختياريّ لبيانات الاعتماد للمزوّدين الذين يتطلبونها.
• إرجاع البيانات الخام (اختياريّ): مرِّر includeRaw: true فتحصل مع كلّ نتيجةٍ على استجابة المزوّد الأصلية غير الموحّدة إلى جانب الموحّدة — للتنقيح أو للمقارنة بين الخام والموحّد.
• يعمل في كلّ البيئات: Node والمتصفّح وDeno وBun، بصيغتَي ESM وCJS، مع أنواع TypeScript كاملة.

التثبيت

npm i quran-api-unified
# أو
pnpm add quran-api-unified

البداية السريعة

import { createQuranClient } from 'quran-api-unified'

const quran = createQuranClient()

const res = await quran.get({
  ref: { surah: 1, ayah: 1 },
  include: ['text', 'audio', 'translation', 'tafsir'],
})

if (res.ok) {
  console.log(res.value.text?.value?.text) // بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ
  console.log(res.value.audio?.value?.url) // رابط التلاوة الصوتية
} else {
  console.error(res.error.code) // خطأ مُصنَّف، ومعه res.attempts بمسار المحاولات
}

النتيجة بيانات مُصنَّفة لا استثناءات: تفحص res.ok، وكلُّ عنصرٍ مطلوب يحمل حالتَه الخاصّة، فإن تعذّر أحدها نجح الباقي.

المصادر المدعومة

| المزوّد | المعرّف | المحتوى | يتطلب مفاتيح؟ | | --- | --- | --- | --- | | Quran Foundation | quran_foundation | نصّ | نعم (OAuth2) | | Al-Quran Cloud | alquran_cloud | نصّ، صوت، ترجمة | لا | | Quran API (Edge) | quran_api_edge | نصّ، صوت | لا | | Quran Hub | quran_hub | نصّ | لا (عبر وسيط) | | Quran Explorer | quran_finder | نصّ | لا (عبر وسيط) | | Tafsir API (spa5k) | spa5k_tafsir | تفسير | لا |

لكلّ مزوّدٍ صفحةٌ مرجعيّة في docs/providers/ تشرح واجهته وسببَ تحويلها على النحو المتّبع.

بيانات الاعتماد

المكتبة تعمل دون أيّ مفتاح مع المزوّدين المفتوحين. أمّا المزوّد الذي يتطلب اعتمادًا (مثل Quran Foundation) فتُمرَّر بياناته عند إنشاء العميل، مفتاحةً بمعرّف المزوّد:

const quran = createQuranClient({
  credentials: {
    quran_foundation: { clientId: '...', secret: '...' },
  },
})

المُحوّل الذي يتطلب اعتمادًا ولم تُزوَّده به يُتخطَّى في الاختيار التلقائيّ، ولا يُطلق خطأً إلا إذا طلبتَه بالاسم صراحةً.

استخدامٌ متقدّم

اختيار مزوّدٍ محدَّد بترتيب رجوعٍ احتياطيّ من اختيارك:

const res = await quran.get({
  ref: { surah: 1, ayah: 1 },
  include: ['text'],
  source: { text: { id: 'quran_hub', fallback: ['quran_finder', 'alquran_cloud'] } },
})

تسجيل مُحوّلٍ مخصّص — وصفةٌ إعلانيّة، لا صنفًا تُوَرِّثه:

import { createQuranClient, type Adapter } from 'quran-api-unified'

const myProvider: Adapter = {
  id: 'my_provider',
  name: 'My Provider',
  capabilities: ['text'],
  auth: 'none',
  text: {
    buildUrl: (q) => `https://example.com/api/ayah/${q.surah}/${q.ayah ?? 1}`,
    transform: (raw, q) => ({
      key: `${q.surah}:${q.ayah ?? 1}`,
      surah: q.surah,
      ayah: q.ayah ?? 1,
      source: 'My Provider',
      text: (raw as { text: string }).text,
    }),
  },
}

const quran = createQuranClient({ adapters: [myProvider] })

التحقق بـ zod عبر مدخلٍ اختياريّ (zod اعتماديّةٌ نظيرةٌ، لا جزءًا من النواة):

import { parseUnifiedVerse } from 'quran-api-unified/zod'

const verse = parseUnifiedVerse(res.value.text?.value)

الدليل الكامل — بما فيه النتائج الجزئية والمتصفّح وCORS — على موقع التوثيق؛ انظر التوثيق أدناه.

التوثيق

التوثيق الكامل — الأدلّة، والمرجع البرمجيّ، وصفحات المزوّدين — في موقع التوثيق (يُبنى بـ VitePress) وفي مجلّد docs/. التوثيق باللغة العربية أساسًا، وله نسخةٌ إنجليزيّة مرافِقة.

المساهمة

نرحّب بالمساهمات، وأكثرها فائدةً إضافةُ مُحوّلاتٍ لمصادر جديدة. دليل المساهمة وعقد المُحوّل في CONTRIBUTING.md.

الترخيص

MIT.