hosteday_flutter: حزمة Flutter لتبسيط التكامل مع HosteDay APIs

عند بناء تطبيق Flutter يعتمد على Backend خارجي، غالبًا تبدأ بكتابة طبقة اتصال خاصة بك للتعامل مع الـ API: تسجيل الدخول، إنشاء الحساب، جلب بيانات المستخدم، تحديث الملف الشخصي، إرسال الهيدرز، التعامل مع الأخطاء، وتكرار نفس الكود في أكثر من مشروع.

ومع الوقت، يصبح هذا التكرار مزعجًا وغير عملي، خصوصًا إذا كنت تعمل على أكثر من تطبيق أو تبني مشاريع تعتمد على نفس البنية الخلفية.

لهذا جاءت حزمة hosteday_flutter لتجعل الاتصال بين تطبيقات Flutter ومنصة HosteDay أسهل، أوضح، وأكثر قابلية لإعادة الاستخدام.

---

ما هي hosteday_flutter؟

hosteday_flutter هي حزمة Flutter بسيطة تساعدك على إرسال الطلبات إلى HosteDay APIs من خلال واجهة موحدة وسهلة الاستخدام.

بدل أن تكتب http.get وhttp.post وتكرر إعدادات الرابط والهيدرز في كل مرة، يمكنك استخدام كائن واحد:

hosteday.get(...)
hosteday.post(...)
hosteday.put(...)
hosteday.patch(...)
hosteday.delete(...)

بهذا تحصل على طريقة منظمة للتعامل مع الـ API داخل تطبيقك.

---

تثبيت الحزمة

hosteday_flutter يمكن تثبيت الحزمة مباشرة من pub.dev:

flutter pub add hosteday_flutter

ثم استيرادها داخل مشروع Flutter:

import 'package:hosteday_flutter/hosteday_flutter.dart';

---

التهيئة الأساسية

أفضل طريقة لاستخدام الحزمة هي إنشاء كائن HosteDayClient مرة واحدة قبل تشغيل التطبيق:

import 'package:flutter/material.dart';
import 'package:hosteday_flutter/hosteday_flutter.dart';

late final HosteDayClient hosteday;

void main() {
  hosteday = HosteDayClient(
    config: const HosteDayConfig(
      baseUrl: 'https://example.hosteday.com',
    ),
  );

  runApp(const App());
}

يجب استبدال الرابط:

https://example.hosteday.com

برابط مشروعك الحقيقي على HosteDay.

---

الفكرة الأساسية

بعد التهيئة، يصبح بإمكانك إرسال الطلبات بسهولة:

final response = await hosteday.get('/api/user');

print(response);

أو:

final response = await hosteday.post(
  '/api/auth/login',
  body: {
    'email': 'user@example.com',
    'password': 'password',
  },
);

print(response);

---

الروابط الافتراضية داخل الحزمة

تحتوي الحزمة على مجموعة روابط افتراضية جاهزة يمكن استخدامها مباشرة من:

hosteday.config

يتم بناء الرابط النهائي بهذا الشكل:

baseUrl + path

مثال:

https://example.hosteday.com/api/auth/login

---

روابط المصادقة الافتراضية

العملية	Method	الاستخدام	الرابط الافتراضي
تسجيل الدخول	POST	hosteday.config.loginPathPost	/api/auth/login
إنشاء حساب	POST	hosteday.config.registerPathPost	/api/auth/register
نسيان كلمة المرور	POST	hosteday.config.forgotPasswordPathPost	/api/auth/forgot-password
إعادة تعيين كلمة المرور	POST	hosteday.config.resetPasswordPathPost	/api/auth/reset-password

---

روابط المستخدم الافتراضية

العملية	Method	الاستخدام	الرابط الافتراضي
جلب بيانات المستخدم	GET	hosteday.config.userShowPathGet	/api/user
تحديث بيانات المستخدم	PUT	hosteday.config.userUpdatePathPut	/api/user
تحديث صورة المستخدم	POST	hosteday.config.userUpdateAvatarPathPost	/api/user/avatar
حذف المستخدم	DELETE	hosteday.config.userDeletePathDelete	/api/user
تسجيل الخروج	POST	hosteday.config.logoutPathPost	/api/logout
تفعيل البريد الإلكتروني	POST	hosteday.config.emailVerifyPathPost	/api/email/verify

---

تسجيل الدخول

مثال تسجيل دخول بسيط:

final response = await hosteday.post(
  hosteday.config.loginPathPost,
  body: {
    'email': 'user@example.com',
    'password': 'password',
  },
);

print(response);

مثال لاستجابة متوقعة:

{
  "token": "USER_TOKEN_HERE",
  "user": {
    "id": 1,
    "name": "Mustafa",
    "email": "user@example.com"
  }
}

---

استخراج التوكن من الاستجابة

قد يرجع الـ API التوكن بأكثر من شكل، لذلك يمكن استخدام دالة بسيطة لاستخراجه:

String? extractToken(Map<String, dynamic> response) {
  final token = response['token'] ?? response['access_token'];

  if (token != null) {
    return token.toString();
  }

  final data = response['data'];

  if (data is Map) {
    final nestedToken = data['token'] ?? data['access_token'];

    if (nestedToken != null) {
      return nestedToken.toString();
    }
  }

  return null;
}

الاستخدام:

final response = await hosteday.post(
  hosteday.config.loginPathPost,
  body: {
    'email': 'user@example.com',
    'password': 'password',
  },
);

final token = extractToken(response);

print(token);

---

إنشاء حساب جديد

final response = await hosteday.post(
  hosteday.config.registerPathPost,
  body: {
    'name': 'Mustafa',
    'email': 'user@example.com',
    'password': 'password',
  },
);

print(response);

---

جلب بيانات المستخدم

إذا كان الرابط يحتاج مصادقة، أرسل التوكن داخل الهيدر:

final response = await hosteday.get(
  hosteday.config.userShowPathGet,
  headers: {
    'Authorization': 'Bearer USER_TOKEN_HERE',
  },
);

print(response);

---

تحديث بيانات المستخدم

final response = await hosteday.put(
  hosteday.config.userUpdatePathPut,
  body: {
    'name': 'Mustafa',
    'email': 'user@example.com',
    'password': 'new-password',
  },
  headers: {
    'Authorization': 'Bearer USER_TOKEN_HERE',
  },
);

print(response);

---

تسجيل الخروج

final response = await hosteday.post(
  hosteday.config.logoutPathPost,
  headers: {
    'Authorization': 'Bearer USER_TOKEN_HERE',
  },
);

print(response);

---

حماية الروابط باستخدام X-Api-Token

في بعض مشاريع HosteDay قد يتم تفعيل ميزة حماية الروابط لمنع الوصول غير المصرح به إلى API.

عند تفعيل هذه الميزة، قد تحتاج إلى إرسال هيدر إضافي باسم:

X-Api-Token

مع الطلبات.

مثال:

final response = await hosteday.get(
  hosteday.config.userShowPathGet,
  headers: {
    'Authorization': 'Bearer USER_TOKEN_HERE',
    'X-Api-Token': 'PROJECT_API_TOKEN_HERE',
  },
);

print(response);

ويمكن استخدام نفس الهيدرز مع POST أو PUT أو PATCH أو DELETE.

مثال تحديث بيانات المستخدم مع حماية الروابط:

final response = await hosteday.put(
  hosteday.config.userUpdatePathPut,
  body: {
    'name': 'Mustafa',
    'email': 'user@example.com',
    'password': 'new-password',
  },
  headers: {
    'Authorization': 'Bearer USER_TOKEN_HERE',
    'X-Api-Token': 'PROJECT_API_TOKEN_HERE',
  },
);

print(response);

لا تضع التوكنات الحقيقية داخل الكود المنشور أو داخل مستودعات عامة. استخدم قيمًا آمنة ومخزنة بطريقة مناسبة حسب بيئة التطبيق.

---

استخدام Endpoint مخصص

الحزمة لا تجبرك على استخدام الروابط الافتراضية فقط. يمكنك تمرير أي رابط API خاص بمشروعك.

مثال إنشاء عنصر:

final response = await hosteday.post(
  '/api/items',
  body: {
    'title': 'New Item',
    'description': 'Item description',
  },
  headers: {
    'Authorization': 'Bearer USER_TOKEN_HERE',
    'X-Api-Token': 'PROJECT_API_TOKEN_HERE',
  },
);

print(response);

مثال تحديث عنصر:

final response = await hosteday.put(
  '/api/items/1',
  body: {
    'title': 'Updated Item',
  },
  headers: {
    'Authorization': 'Bearer USER_TOKEN_HERE',
    'X-Api-Token': 'PROJECT_API_TOKEN_HERE',
  },
);

print(response);

مثال حذف عنصر:

final response = await hosteday.delete(
  '/api/items/1',
  headers: {
    'Authorization': 'Bearer USER_TOKEN_HERE',
    'X-Api-Token': 'PROJECT_API_TOKEN_HERE',
  },
);

print(response);

---

الطرق المدعومة

تدعم الحزمة الطرق الأساسية للتعامل مع APIs:

hosteday.get('/api/path');

hosteday.post(
  '/api/path',
  body: {},
);

hosteday.put(
  '/api/path',
  body: {},
);

hosteday.patch(
  '/api/path',
  body: {},
);

hosteday.delete('/api/path');

---

التعامل مع الأخطاء

يمكن التقاط أخطاء الحزمة باستخدام HosteDayException:

try {
  final response = await hosteday.get(
    hosteday.config.userShowPathGet,
    headers: {
      'Authorization': 'Bearer USER_TOKEN_HERE',
      'X-Api-Token': 'PROJECT_API_TOKEN_HERE',
    },
  );

  print(response);
} on HosteDayException catch (e) {
  print(e.message);
  print(e.statusCode);
  print(e.error);
} catch (e) {
  print(e);
}

هذا يساعدك على عرض رسائل مناسبة للمستخدم بدل توقف التطبيق أو إظهار خطأ غير واضح.

---

مثال Flutter كامل

يوجد مثال كامل داخل الحزمة يوضح طريقة استخدام hosteday_flutter في تطبيق Flutter مع واجهة بسيطة لتجربة:

• تسجيل الدخول
• إنشاء حساب
• جلب بيانات المستخدم
• تحديث بيانات المستخدم
• تسجيل الخروج
• إرسال Authorization
• إرسال X-Api-Token
• عرض استجابة الـ API بشكل منظم

يمكنك الاطلاع على المثال من هنا:

example/lib/main.dart

---

لماذا هذه الحزمة مفيدة؟

بدل تكرار منطق الاتصال في كل مشروع، توفر لك hosteday_flutter طبقة جاهزة ومنظمة للتعامل مع HosteDay APIs.

هذا يجعل الكود:

• أسهل في القراءة
• أسهل في الصيانة
• قابلًا لإعادة الاستخدام
• مناسبًا لمشاريع متعددة
• أبسط عند التعامل مع المصادقة والهيدرز

---

أفضل الممارسات

• لا تضع التوكنات الحقيقية داخل الكود.
• استخدم Authorization للروابط التي تحتاج تسجيل دخول.
• استخدم X-Api-Token عند تفعيل حماية الروابط.
• استخدم الروابط الافتراضية من hosteday.config عندما تكون مناسبة.
• استخدم روابط مخصصة عند الحاجة.
• تعامل مع الأخطاء باستخدام try/catch.
• لا تعرض تفاصيل الأخطاء الحساسة للمستخدم النهائي.

---

الخلاصة

حزمة hosteday_flutter تجعل ربط تطبيق Flutter مع HosteDay APIs أكثر بساطة وتنظيمًا.

يمكنك البدء بإعداد بسيط، ثم استخدام دوال واضحة مثل get وpost وput وdelete للتعامل مع مختلف أجزاء الـ API، مع دعم الهيدرز، التوكنات، وحماية الروابط.

إذا كنت تبني تطبيق Flutter يعتمد على HosteDay، فهذه الحزمة تختصر عليك الكثير من الكود المتكرر وتمنحك طريقة موحدة للتعامل مع الـ Backend.