🔐 المصادقة

إنشاء الحسابات وتسجيل الدخول والحصول على رموز الوصول

POST /auth/register تسجيل حساب جديد

إنشاء حساب مستخدم جديد في السجل

المعاملات (JSON Body)

المعامل	النوع	مطلوب	الوصف
username	string	✅	اسم المستخدم (3-30 حرف، عربي أو إنجليزي)
email	string	✅	البريد الإلكتروني
password	string	✅	كلمة المرور (8 أحرف كحد أدنى، حرف كبير + صغير + رقم + رمز)
display_name	string	❌	الاسم المعروض

مثال

curl -X POST https://sila-hub.dev/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "مطور_جديد",
    "email": "dev@example.com",
    "password": "MyPass@123",
    "display_name": "مطور تطبيقات"
  }'

الاستجابة 201

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 1,
    "username": "مطور_جديد",
    "display_name": "مطور تطبيقات"
  }
}

POST /auth/login تسجيل الدخول

تسجيل الدخول والحصول على رمز JWT (صالح لمدة 30 يوماً)

المعاملات (JSON Body)

المعامل	النوع	مطلوب	الوصف
username	string	✅	اسم المستخدم
password	string	✅	كلمة المرور

مثال

curl -X POST https://sila-hub.dev/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "مطور_جديد", "password": "MyPass@123"}'

POST /auth/token إنشاء رمز API 🔒 مصادقة

إنشاء رمز API طويل الأمد للاستخدام في سطر الأوامر (sad-pkg)

المعاملات (JSON Body)

المعامل	النوع	مطلوب	الوصف
name	string	✅	اسم وصفي للرمز

📦 الحزم

البحث عن الحزم وعرض تفاصيلها وتنزيلها ونشرها

GET /packages/search البحث عن حزم

البحث في الحزم بالاسم أو الوصف (يدعم العربية والإنجليزية)

معاملات الاستعلام (Query Parameters)

المعامل	النوع	الافتراضي	الوصف
q	string	—	نص البحث
limit	number	20	الحد الأقصى للنتائج (1-50)
offset	number	0	بداية النتائج (للتصفح)
category	string	—	تصفية حسب التصنيف

مثال

curl "https://sila-hub.dev/api/v1/packages/search?q=رياضيات&limit=10"

GET /packages/{name} معلومات حزمة

عرض المعلومات الكاملة لحزمة محددة مع الإصدارات والمالكين

GET /packages/{name}/versions قائمة الإصدارات

عرض جميع إصدارات الحزمة مع حالة كل إصدار

GET /packages/{name}/{version} معلومات إصدار

عرض معلومات إصدار محدد مع التبعيات

GET /packages/{name}/{version}/download تنزيل الحزمة

تحميل ملف الحزمة (.tar.gz) مع التحقق من SHA256

مثال

curl -O "https://sila-hub.dev/api/v1/packages/رياضيات/1.0.0/download"
# أو باستخدام أداة الحزم:
sad-pkg add رياضيات

POST /packages/publish نشر حزمة 🔒 مصادقة

نشر حزمة جديدة أو إصدار جديد — الملف يجب أن يكون .tar.gz أو .zip (حد أقصى 50MB)

المعاملات (Multipart Form Data)

المعامل	النوع	مطلوب	الوصف
package	file	✅	ملف الحزمة المضغوط
metadata	JSON	✅	بيانات الحزمة الوصفية

مثال

# باستخدام أداة الحزم (الطريقة المُوصى بها):
sad-pkg publish

# أو يدوياً:
curl -X POST https://sila-hub.dev/api/v1/packages/publish \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "package=@my-package-1.0.0.tar.gz" \
  -F 'metadata={"name":"حزمتي","version":"1.0.0","description":"وصف الحزمة"}'

DELETE /packages/{name}/{version}/yank سحب إصدار 🔒 مصادقة

سحب إصدار من التداول (منع التنزيل مع بقاء بيانات الإصدار)

GET /packages/{name}/skill ملف المهارة

جلب ملف المهارة (skill.md) الخاص بالحزمة — يستخدمه الذكاء الاصطناعي لفهم كيفية استخدام الحزمة

👤 المستخدم

معلومات المستخدم وحزمه المنشورة

GET /user/profile الملف الشخصي 🔒 مصادقة

عرض بيانات المستخدم الحالي

GET /user/packages حزم المستخدم 🔒 مصادقة

عرض الحزم المنشورة بواسطة المستخدم الحالي

📊 الإحصائيات

إحصائيات وتصنيفات السجل

GET /stats ملخص الإحصائيات

عدد الحزم والإصدارات والمستخدمين والتنزيلات

الاستجابة 200

{
  "total_packages": 42,
  "total_versions": 156,
  "total_users": 15,
  "total_downloads": 1280
}

GET /stats/downloads التنزيلات اليومية

إحصائيات التنزيلات خلال فترة زمنية

معاملات الاستعلام

المعامل	النوع	الافتراضي	الوصف
days	number	30	عدد الأيام (1-365)

GET /stats/categories التصنيفات

قائمة جميع تصنيفات الحزم المتاحة

⚠️ معالجة الأخطاء

جميع الأخطاء تُرجع بنفس البنية مع أكواد مُفصّلة

{
  "success": false,
  "error": {
    "code": "PKG_001",
    "message": "الحزمة غير موجودة",
    "message_en": "Package not found",
    "explain": "شرح تفصيلي للمشكلة",
    "hint": "الحل المقترح أو الخطوة التالية"
  },
  "request_id": "abc123def456",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

أكواد الأخطاء

🔐 المصادقة (AUTH)

الكود	HTTP	الوصف
AUTH_001	400	بيانات التسجيل ناقصة
AUTH_002	409	اسم المستخدم مستخدم
AUTH_003	409	البريد مستخدم
AUTH_004	401	بيانات دخول خاطئة
AUTH_005	403	الحساب معطل

📦 الحزم (PKG)

الكود	HTTP	الوصف
PKG_001	404	الحزمة غير موجودة
PKG_002	404	الإصدار غير موجود
PKG_003	409	الإصدار موجود مسبقاً
PKG_004	403	لا صلاحية
PKG_005	400	اسم غير صالح
PKG_006	400	إصدار غير صالح
PKG_007	410	إصدار مسحوب
PKG_008	400	مشكلة في الملف

⚙️ النظام

نقاط فحص حالة الخادم

GET / معلومات API

معلومات عامة عن واجهة API والمسارات المتاحة

GET /health فحص صحة الخادم

يُرجع حالة الخادم وقاعدة البيانات — مفيد للمراقبة